[svn] commit: r2605 - /branches/trac232/src/lib/datasrc/data_source.h

BIND 10 source code commits bind10-changes at lists.isc.org
Wed Jul 28 13:18:12 UTC 2010


Author: jelte
Date: Wed Jul 28 13:18:11 2010
New Revision: 2605

Log:
header documentation for the DataSrcTransaction class

Modified:
    branches/trac232/src/lib/datasrc/data_source.h

Modified: branches/trac232/src/lib/datasrc/data_source.h
==============================================================================
--- branches/trac232/src/lib/datasrc/data_source.h (original)
+++ branches/trac232/src/lib/datasrc/data_source.h Wed Jul 28 13:18:11 2010
@@ -182,10 +182,60 @@
 //    virtual ~DataSrcTransaction() {};
 //};
 
+///
+/// \brief The \c DataSrcTransaction serves as a data container and
+/// resource holder for transactions on writable data sources.
+///
+/// Instantiating this class does not actually start a transaction.
+/// Rather, it is passed to the actual data source's startTransaction()
+/// method, which starts the transaction and fills this object with
+/// the data that data source needs in order to perform the write
+/// commands later. When this transaction object is destroyed, and
+/// the transaction has been started, but not committed (with
+/// commitTransaction()), rollbackTransaction() in the
+/// data source is called. That way, we can make sure unfinished 
+/// transactions do not linger.
+///
+/// To help prevent logic errors in the use of the transaction object,
+/// it keeps a 'state', which is one of INIT, RUNNING, or DONE.
+/// startTransaction() in a data source MUST check that state is INIT,
+/// and set it to RUNNING (on success, of course).
+/// Any actual operation within the transaction MUST check the state is
+/// RUNNING.
+/// commitTransaction() and rollbackTransaction() MUST check the state
+/// is RUNNING, and set it to DONE.
+///
+/// Apart from holding the resource for the open transaction, this
+/// class is also intended to store data-source specific data during
+/// that transaction. One example is that for the Sqlite3-data source,
+/// it stores the zone_id value. Datasources can store arbitrary data
+/// in the ElementPtr() returned by getData().
+/// 
+/// This class always stores some basic information, given at 
+/// instantiation time. Apart from the getters and setters for these, 
+/// and the desctructor, this class should not have any methods that 
+/// contain logic.
+///
 class DataSrcTransaction {
 public:
     enum states { INIT, RUNNING, DONE };
 
+    /// \brief Constructs a DataSrcTransaction object
+    ///
+    /// Constructs a DataSrcTransaction object for use with
+    /// the given data source, for operations on the given zone name,
+    /// in the given zone class. If the data source is a meta data
+    /// source that supports searching for the real one, the internal
+    /// data source pointer can be set to the data source that actually
+    /// holds the zone, but this will not happen until the transaction
+    /// is actually started (by the data sources startTransaction()
+    /// method).
+    ///
+    /// After construction, the transaction state will be INIT.
+    /// \param data_source The data source to perform operations on
+    /// \param zone_name The name of the zone to perform operations on
+    /// \param zone_class The RRClass of the zone to perform operations on.
+    ///
     explicit DataSrcTransaction(DataSrc *data_source,
                                 const isc::dns::Name& zone_name,
                                 const isc::dns::RRClass& zone_class) :
@@ -194,12 +244,40 @@
                                 _data_source(data_source),
                                 _state(INIT) {};
     ~DataSrcTransaction();
+
+    /// \brief Returns the current state of the transaction
+    /// \return state
     states getState() { return (_state); };
+
+    /// \brief Sets the state of the transaction
+    /// \param state The new state
     void setState(states state) { _state = state; };
+
+    /// \brief Returns the base ElementPtr of the arbitrary
+    /// datasource-specific data.
+    /// The exact contents of this ptr are determined by the
+    /// data source, and no assumptions about its contents should
+    /// be made by the caller.
+    /// \return ElementPtr containing transaction data
     isc::data::ElementPtr getData() { return (_data); };
+
+    /// \brief Sets the base ElementsPtr of the arbitrary
+    /// datasource-specific data. This function should only be called
+    /// by the data source, in the startTransaction() method.
+    /// \param data The ElementPtr containing data
     void setData(isc::data::ElementPtr data) { _data = data; };
+    
+    /// \brief Returns the name of the zone this transaction is about
+    /// \return zone name
     const isc::dns::Name getZoneName() { return (_zone_name); };
+
+    /// \brief Returns the RRClass of the zone this transaction is about
+    /// \return RRClass
     const isc::dns::RRClass getZoneClass() { return (_zone_class); };
+
+    /// \brief Returns a pointer to the data source the zone was
+    /// found in.
+    /// \return DataSrc* pointer
     DataSrc* getDataSource() { return (_data_source); };
 
 private:




More information about the bind10-changes mailing list