System.Data.SQLite
Check-in [3bf2ed2311]
Not logged in

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:More work on doc comments.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | sessions
Files: files | file ages | folders
SHA1: 3bf2ed2311a4de737830f4601d6e7d0a16cdee0d
User & Date: mistachkin 2017-10-13 21:01:50
Context
2017-10-14
02:24
Yet more work on doc comments. check-in: 47a190338f user: mistachkin tags: sessions
2017-10-13
21:01
More work on doc comments. check-in: 3bf2ed2311 user: mistachkin tags: sessions
20:37
Initial work on doc comments. check-in: e1e7276789 user: mistachkin tags: sessions
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to System.Data.SQLite/SQLiteSession.cs.

   282    282           );
   283    283       }
   284    284       #endregion
   285    285   
   286    286       ///////////////////////////////////////////////////////////////////////////
   287    287   
   288    288       #region SQLiteSessionHelpers Class
          289  +    /// <summary>
          290  +    /// This class contains some static helper methods for use within this
          291  +    /// subsystem.
          292  +    /// </summary>
   289    293       internal static class SQLiteSessionHelpers
   290    294       {
   291    295           #region Public Methods
          296  +        /// <summary>
          297  +        /// This method checks the byte array specified by the caller to make
          298  +        /// sure it will be usable.
          299  +        /// </summary>
          300  +        /// <param name="rawData">
          301  +        /// A byte array provided by the caller into one of the public methods
          302  +        /// for the classes that belong to this subsystem.  This value cannot
          303  +        /// be null or represent an empty array; otherwise, an appropriate
          304  +        /// exception will be thrown.
          305  +        /// </param>
   292    306           public static void CheckRawData(
   293    307               byte[] rawData
   294    308               )
   295    309           {
   296    310               if (rawData == null)
   297    311                   throw new ArgumentNullException("rawData");
   298    312   
................................................................................
   305    319           #endregion
   306    320       }
   307    321       #endregion
   308    322   
   309    323       ///////////////////////////////////////////////////////////////////////////
   310    324   
   311    325       #region SQLiteConnectionLock Class
          326  +    /// <summary>
          327  +    /// This class is used to hold the native connection handle associated with
          328  +    /// a <see cref="SQLiteConnection" /> open until this subsystem is totally
          329  +    /// done with it.  This class is for internal use by this subsystem only.
          330  +    /// </summary>
   312    331       internal abstract class SQLiteConnectionLock : IDisposable
   313    332       {
   314    333           #region Private Constants
          334  +        /// <summary>
          335  +        /// The SQL statement used when creating the native statement handle.
          336  +        /// There are no special requirements for this other than counting as
          337  +        /// an "open statement handle".
          338  +        /// </summary>
   315    339           private const string LockNopSql = "SELECT 1;";
   316    340   
   317    341           ///////////////////////////////////////////////////////////////////////
   318    342   
          343  +        /// <summary>
          344  +        /// The format of the error message used when reporting, during object
          345  +        /// disposal, that the statement handle is still open (i.e. because
          346  +        /// this situation is considered a fairly serious programming error).
          347  +        /// </summary>
   319    348           private const string StatementMessageFormat =
   320    349               "Connection lock object was {0} with statement {1}";
   321    350           #endregion
   322    351   
   323    352           ///////////////////////////////////////////////////////////////////////
   324    353   
   325    354           #region Private Data
          355  +        /// <summary>
          356  +        /// The wrapped native connection handle associated with this lock.
          357  +        /// </summary>
   326    358           private SQLiteConnectionHandle handle;
          359  +
          360  +        /// <summary>
          361  +        /// The flags associated with the connection represented by the
          362  +        /// <see cref="handle" /> value.
          363  +        /// </summary>
   327    364           private SQLiteConnectionFlags flags;
   328    365   
   329    366           ///////////////////////////////////////////////////////////////////////
   330    367   
          368  +        /// <summary>
          369  +        /// The native statement handle for this lock.  The garbage collector
          370  +        /// cannot cause this statement to be finalized; therefore, it will
          371  +        /// serve to hold the associated native connection open until it is
          372  +        /// freed manually using the <see cref="Unlock" /> method.
          373  +        /// </summary>
   331    374           private IntPtr statement;
   332    375           #endregion
   333    376   
   334    377           ///////////////////////////////////////////////////////////////////////
   335    378   
   336    379           #region Public Constructors
          380  +        /// <summary>
          381  +        /// Constructs a new instance of this class using the specified native
          382  +        /// connection handle and associated flags.
          383  +        /// </summary>
          384  +        /// <param name="handle">
          385  +        /// The wrapped native connection handle to be associated with this
          386  +        /// lock.
          387  +        /// </param>
          388  +        /// <param name="flags">
          389  +        /// The flags associated with the connection represented by the
          390  +        /// <paramref name="handle" /> value.
          391  +        /// </param>
          392  +        /// <param name="autoLock">
          393  +        /// Non-zero if the <see cref="Lock" /> method should be called prior
          394  +        /// to returning from this constructor.
          395  +        /// </param>
   337    396           public SQLiteConnectionLock(
   338    397               SQLiteConnectionHandle handle,
   339         -            SQLiteConnectionFlags flags
          398  +            SQLiteConnectionFlags flags,
          399  +            bool autoLock
   340    400               )
   341    401           {
   342    402               this.handle = handle;
   343    403               this.flags = flags;
   344    404   
   345         -            Lock();
          405  +            if (autoLock)
          406  +                Lock();
   346    407           }
   347    408           #endregion
   348    409   
   349    410           ///////////////////////////////////////////////////////////////////////
   350    411   
   351    412           #region Protected Methods
          413  +        /// <summary>
          414  +        /// Queries and returns the wrapped native connection handle for this
          415  +        /// instance.
          416  +        /// </summary>
          417  +        /// <returns>
          418  +        /// The wrapped native connection handle for this instance -OR- null
          419  +        /// if it is unavailable.
          420  +        /// </returns>
   352    421           protected SQLiteConnectionHandle GetHandle()
   353    422           {
   354    423               return handle;
   355    424           }
   356    425   
   357    426           ///////////////////////////////////////////////////////////////////////
   358    427   
          428  +        /// <summary>
          429  +        /// Queries and returns the flags associated with the connection for
          430  +        /// this instance.
          431  +        /// </summary>
          432  +        /// <returns>
          433  +        /// The <see cref="SQLiteConnectionFlags" /> value.  There is no return
          434  +        /// value reserved to indicate an error.
          435  +        /// </returns>
   359    436           protected SQLiteConnectionFlags GetFlags()
   360    437           {
   361    438               return flags;
   362    439           }
   363    440   
   364    441           ///////////////////////////////////////////////////////////////////////
   365    442   
          443  +        /// <summary>
          444  +        /// Queries and returns the native connection handle for this instance.
          445  +        /// </summary>
          446  +        /// <returns>
          447  +        /// The native connection handle for this instance.  If this value is
          448  +        /// unavailable or invalid an exception will be thrown.
          449  +        /// </returns>
   366    450           protected IntPtr GetIntPtr()
   367    451           {
   368    452               if (handle == null)
   369    453               {
   370    454                   throw new InvalidOperationException(
   371    455                       "Connection lock object has an invalid handle.");
   372    456               }
................................................................................
   382    466               return handlePtr;
   383    467           }
   384    468           #endregion
   385    469   
   386    470           ///////////////////////////////////////////////////////////////////////
   387    471   
   388    472           #region Public Methods
          473  +        /// <summary>
          474  +        /// This method attempts to "lock" the associated native connection
          475  +        /// handle by preparing a SQL statement that will not be finalized
          476  +        /// until the <see cref="Unlock" /> method is called (i.e. and which
          477  +        /// cannot be done by the garbage collector).  If the statement is
          478  +        /// already prepared, nothing is done.  If the statement cannot be
          479  +        /// prepared for any reason, an exception will be thrown.
          480  +        /// </summary>
   389    481           public void Lock()
   390    482           {
   391    483               CheckDisposed();
   392    484   
   393    485               if (statement != IntPtr.Zero)
   394    486                   return;
   395    487   
................................................................................
   419    511                       pSql = IntPtr.Zero;
   420    512                   }
   421    513               }
   422    514           }
   423    515   
   424    516           ///////////////////////////////////////////////////////////////////////
   425    517   
          518  +        /// <summary>
          519  +        /// This method attempts to "unlock" the associated native connection
          520  +        /// handle by finalizing the previously prepared statement.  If the
          521  +        /// statement is already finalized, nothing is done.  If the statement
          522  +        /// cannot be finalized for any reason, an exception will be thrown.
          523  +        /// </summary>
   426    524           public void Unlock()
   427    525           {
   428    526               CheckDisposed();
   429    527   
   430    528               if (statement == IntPtr.Zero)
   431    529                   return;
   432    530   
................................................................................
   439    537               statement = IntPtr.Zero;
   440    538           }
   441    539           #endregion
   442    540   
   443    541           ///////////////////////////////////////////////////////////////////////
   444    542   
   445    543           #region IDisposable Members
          544  +        /// <summary>
          545  +        /// Disposes of this object instance.
          546  +        /// </summary>
   446    547           public void Dispose()
   447    548           {
   448    549               Dispose(true);
   449    550               GC.SuppressFinalize(this);
   450    551           }
   451    552           #endregion
   452    553   
   453    554           ///////////////////////////////////////////////////////////////////////
   454    555   
   455    556           #region IDisposable "Pattern" Members
          557  +        /// <summary>
          558  +        /// Non-zero if this object instance has been disposed.
          559  +        /// </summary>
   456    560           private bool disposed;
          561  +
          562  +        /// <summary>
          563  +        /// Throws an exception if this object instance has been disposed.
          564  +        /// </summary>
   457    565           private void CheckDisposed() /* throw */
   458    566           {
   459    567   #if THROW_ON_DISPOSED
   460    568               if (disposed)
   461    569               {
   462    570                   throw new ObjectDisposedException(
   463    571                       typeof(SQLiteConnectionLock).Name);
   464    572               }
   465    573   #endif
   466    574           }
   467    575   
   468    576           ///////////////////////////////////////////////////////////////////////
   469    577   
          578  +        /// <summary>
          579  +        /// Disposes or finalizes this object instance.
          580  +        /// </summary>
          581  +        /// <param name="disposing">
          582  +        /// Non-zero if this object is being disposed; otherwise, this object
          583  +        /// is being finalized.
          584  +        /// </param>
   470    585           protected virtual void Dispose(bool disposing)
   471    586           {
   472    587               try
   473    588               {
   474    589                   if (!disposed)
   475    590                   {
   476    591                       //if (disposing)
................................................................................
   525    640               }
   526    641           }
   527    642           #endregion
   528    643   
   529    644           ///////////////////////////////////////////////////////////////////////
   530    645   
   531    646           #region Destructor
          647  +        /// <summary>
          648  +        /// Finalizes this object instance.
          649  +        /// </summary>
   532    650           ~SQLiteConnectionLock()
   533    651           {
   534    652               Dispose(false);
   535    653           }
   536    654           #endregion
   537    655       }
   538    656       #endregion
................................................................................
  1663   1781   
  1664   1782           #region Public Constructors
  1665   1783           public SQLiteSession(
  1666   1784               SQLiteConnectionHandle handle,
  1667   1785               SQLiteConnectionFlags flags,
  1668   1786               string databaseName
  1669   1787               )
  1670         -            : base(handle, flags)
         1788  +            : base(handle, flags, true)
  1671   1789           {
  1672   1790               this.databaseName = databaseName;
  1673   1791   
  1674   1792               InitializeHandle();
  1675   1793           }
  1676   1794           #endregion
  1677   1795   
................................................................................
  2127   2245       internal class SQLiteChangeSetBase : SQLiteConnectionLock
  2128   2246       {
  2129   2247           #region Private Constructors
  2130   2248           internal SQLiteChangeSetBase(
  2131   2249               SQLiteConnectionHandle handle,
  2132   2250               SQLiteConnectionFlags flags
  2133   2251               )
  2134         -            : base(handle, flags)
         2252  +            : base(handle, flags, true)
  2135   2253           {
  2136   2254               // do nothing.
  2137   2255           }
  2138   2256           #endregion
  2139   2257   
  2140   2258           ///////////////////////////////////////////////////////////////////////
  2141   2259