[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