BIND 10 trac2435_2, updated. 631366a33bb06d01547c0789edfadde7a17228bd [2435] Explain why using the rrset collection is not allowed after calling ZoneUpdater::commit()

[BIND 10 source code commits]

The branch, trac2435_2 has been updated
       via  631366a33bb06d01547c0789edfadde7a17228bd (commit)
       via  e05c0b3ebb376233dd9648732fb5c992bb72e242 (commit)
       via  a60ee6bbefe447f7ce863641dd88cdb1d3f0766b (commit)
      from  d7fd34a4bf69c07812461671ac8d8f0dde0ee440 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 631366a33bb06d01547c0789edfadde7a17228bd
Author: Mukund Sivaraman <muks at isc.org>
Date:   Mon Jan 21 12:17:40 2013 +0530

    [2435] Explain why using the rrset collection is not allowed after calling ZoneUpdater::commit()

commit e05c0b3ebb376233dd9648732fb5c992bb72e242
Author: Mukund Sivaraman <muks at isc.org>
Date:   Mon Jan 21 12:07:20 2013 +0530

    [2435] Explain why modifying data is not allowed after creating the rrset collection

commit a60ee6bbefe447f7ce863641dd88cdb1d3f0766b
Author: Mukund Sivaraman <muks at isc.org>
Date:   Mon Jan 21 12:00:14 2013 +0530

    [2435] Make isc::datasrc::RRsetCollectionBase complete

-----------------------------------------------------------------------

Summary of changes:
 src/lib/datasrc/database.cc             |   12 ------------
 src/lib/datasrc/rrset_collection_base.h |   15 ++++++++++-----
 src/lib/datasrc/zone.h                  |   28 ++++++++++++++++++----------
 3 files changed, 28 insertions(+), 27 deletions(-)

-----------------------------------------------------------------------
diff --git a/src/lib/datasrc/database.cc b/src/lib/datasrc/database.cc
index 4b5b8d1..195793a 100644
--- a/src/lib/datasrc/database.cc
+++ b/src/lib/datasrc/database.cc
@@ -1398,18 +1398,6 @@ public:
     void disableWrapper() {
         disable();
     }
-
-protected:
-    // TODO: RRsetCollectionBase::Iter is not implemented and the
-    // following two methods just throw.
-
-    virtual RRsetCollectionBase::IterPtr getBeginning() {
-        isc_throw(NotImplemented, "This method is not implemented.");
-    }
-
-    virtual RRsetCollectionBase::IterPtr getEnd() {
-        isc_throw(NotImplemented, "This method is not implemented.");
-    }
 };
 
 //
diff --git a/src/lib/datasrc/rrset_collection_base.h b/src/lib/datasrc/rrset_collection_base.h
index afc8959..0abaa82 100644
--- a/src/lib/datasrc/rrset_collection_base.h
+++ b/src/lib/datasrc/rrset_collection_base.h
@@ -27,9 +27,8 @@ class ZoneUpdater;
 
 /// \brief datasrc derivation of \c isc::dns::RRsetCollectionBase.
 ///
-/// This is an abstract class that adds datasrc related detail to
-/// \c isc::dns::RRsetCollectionBase. Derived classes need to complete
-/// the implementation (add iterator support, etc.) before using it.
+/// This is a default datasrc implementation of
+/// \c isc::dns::RRsetCollectionBase that adds datasrc related detail.
 class RRsetCollectionBase : public isc::dns::RRsetCollectionBase {
 public:
     /// \brief Constructor.
@@ -93,7 +92,10 @@ protected:
     /// \throw isc::dns::RRsetCollectionError if using the iterator
     /// results in some underlying datasrc error, or if \c disable() was
     /// called.
-    virtual IterPtr getBeginning() = 0;
+    /// \throw isc::NotImplemented as it's not implemented currently.
+    virtual IterPtr getBeginning() {
+        isc_throw(NotImplemented, "This method is not implemented.");
+    }
 
     /// \brief See \c isc::dns::RRsetCollectionBase::getEnd() for
     /// documentation.
@@ -101,7 +103,10 @@ protected:
     /// \throw isc::dns::RRsetCollectionError if using the iterator
     /// results in some underlying datasrc error, or if \c disable() was
     /// called.
-    virtual IterPtr getEnd() = 0;
+    /// \throw isc::NotImplemented as it's not implemented currently.
+    virtual IterPtr getEnd() {
+        isc_throw(NotImplemented, "This method is not implemented.");
+    }
 
 private:
     ZoneUpdater& updater_;
diff --git a/src/lib/datasrc/zone.h b/src/lib/datasrc/zone.h
index 01d6a83..3b720ae 100644
--- a/src/lib/datasrc/zone.h
+++ b/src/lib/datasrc/zone.h
@@ -821,12 +821,16 @@ public:
     /// The behavior of the RRsetCollection is similar to the behavior
     /// of the \c Zonefinder returned by \c getFinder().
     /// Implementations of \c ZoneUpdater may not allow adding or
-    /// deleting RRsets after \c getRRsetCollection() is called.
-    /// Implementations of \c ZoneUpdater may disable a previously
-    /// returned \c RRsetCollection after \c commit() is called. If an
-    /// \c RRsetCollection is disabled, using methods such as \c find()
-    /// and using its iterator would cause an exception to be
-    /// thrown. See \c isc::datasrc::RRsetCollectionBase for details.
+    /// deleting RRsets after \c getRRsetCollection() is called. This is
+    /// because iterating the collection may result in unexpected
+    /// behavior if the underlying data is updated.  Implementations of
+    /// \c ZoneUpdater may disable a previously returned
+    /// \c RRsetCollection after \c commit() is called. Even in this
+    /// case, using existing iterators may result in unexpected behavior
+    /// after \c commit() is called. If an \c RRsetCollection is
+    /// disabled, using methods such as \c find() and using its iterator
+    /// would cause an exception to be thrown. See
+    /// \c isc::datasrc::RRsetCollectionBase for details.
     virtual isc::datasrc::RRsetCollectionBase& getRRsetCollection() = 0;
 
     /// Add an RRset to a zone via the updater
@@ -877,8 +881,10 @@ public:
     /// \c DataSourceError exception.
     ///
     /// Implementations of \c ZoneUpdater may not allow adding or
-    /// deleting RRsets after \c getRRsetCollection() is called. In this
-    /// case, implementations throw an \c InvalidOperation exception.
+    /// deleting RRsets after \c getRRsetCollection() is called. This is
+    /// because iterating the collection may result in unexpected
+    /// behavior if the underlying data is updated. In this case,
+    /// implementations throw an \c InvalidOperation exception.
     ///
     /// If journaling was requested when getting this updater, it will reject
     /// to add the RRset if the squence doesn't look like and IXFR (see
@@ -952,8 +958,10 @@ public:
     /// \c DataSourceError exception.
     ///
     /// Implementations of \c ZoneUpdater may not allow adding or
-    /// deleting RRsets after \c getRRsetCollection() is called. In this
-    /// case, implementations throw an \c InvalidOperation exception.
+    /// deleting RRsets after \c getRRsetCollection() is called. This is
+    /// because iterating the collection may result in unexpected
+    /// behavior if the underlying data is updated. In this case,
+    /// implementations throw an \c InvalidOperation exception.
     ///
     /// If journaling was requested when getting this updater, it will reject
     /// to add the RRset if the squence doesn't look like and IXFR (see