BIND 10 master, updated. 717d619224d93b6dc6da0cf6267deffc31e130ad Merge branch 'master' into trac2435_2
BIND 10 source code commits
bind10-changes at lists.isc.org
Tue Jan 29 03:27:46 UTC 2013
The branch, master has been updated
via 717d619224d93b6dc6da0cf6267deffc31e130ad (commit)
via 10fece1ac6ec02b033f00689fc31ac4f93570dda (commit)
via 9a7784d748031b97dbb5a55fed84dcca254096d5 (commit)
via 12807b1d6e3a0846198bcc062978c077ac101b91 (commit)
via b22bc32b2776aa8904ee4fae2e9f6b075eace0f4 (commit)
via df5cb12f60fc4f22b24218a54bf428f403cabe22 (commit)
via 72383e89593fdc91a83b0ffe875a4fdb5114fbfc (commit)
via 79b78d6538b85a97e1a84aec63928a6bd0251218 (commit)
via 2352105cc77dd16a583c8f4fdcaf9d680e450344 (commit)
via 848cc407b16d4874dc5abec493248cd64db018c6 (commit)
via 1f6f8905d7319519c6f2ebd5864eeb4d6d700d03 (commit)
via 631366a33bb06d01547c0789edfadde7a17228bd (commit)
via e05c0b3ebb376233dd9648732fb5c992bb72e242 (commit)
via a60ee6bbefe447f7ce863641dd88cdb1d3f0766b (commit)
via d7fd34a4bf69c07812461671ac8d8f0dde0ee440 (commit)
via 1bb3b6b661cc500b2a7cad2447347a23b7b1fadc (commit)
via d5a2bb8d02bb017405ac6f79e2eeffcb7fd23052 (commit)
via 9de5d287390383e072dbb2c4cbf9d60253893e41 (commit)
via 2887502a9e0084cb16c79aba684a65f9d4fda69a (commit)
from 4c4e2711beeb2eed8104055cf66dd4e8151c4fd1 (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 717d619224d93b6dc6da0cf6267deffc31e130ad
Merge: 10fece1 4c4e271
Author: Mukund Sivaraman <muks at isc.org>
Date: Tue Jan 29 08:22:23 2013 +0530
Merge branch 'master' into trac2435_2
Conflicts:
src/lib/datasrc/zone.h
src/lib/python/isc/datasrc/updater_inc.cc
-----------------------------------------------------------------------
Summary of changes:
src/lib/datasrc/database.cc | 19 +-----
src/lib/datasrc/rrset_collection_base.h | 54 ++++++++++------
src/lib/datasrc/tests/database_unittest.cc | 20 ++++--
.../datasrc/tests/master_loader_callbacks_test.cc | 2 +-
src/lib/datasrc/tests/zone_loader_unittest.cc | 19 ++----
src/lib/datasrc/zone.h | 68 +++++++++++++++-----
src/lib/datasrc/zone_finder.h | 1 -
src/lib/datasrc/zone_loader.cc | 3 +-
src/lib/dns/python/rrset_collection_python_inc.cc | 39 ++++++++++-
src/lib/dns/rrset_collection_base.h | 38 +++++++++--
src/lib/python/isc/datasrc/updater_inc.cc | 51 ++++++++++++---
11 files changed, 223 insertions(+), 91 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/datasrc/database.cc b/src/lib/datasrc/database.cc
index 0ca9226..f6d8252 100644
--- a/src/lib/datasrc/database.cc
+++ b/src/lib/datasrc/database.cc
@@ -1385,7 +1385,7 @@ DatabaseClient::getIterator(const isc::dns::Name& name,
return (iterator);
}
-/// \brief datasrc implementation of RRsetCollectionBase.
+/// \brief Database implementation of RRsetCollectionBase.
class RRsetCollection : public isc::datasrc::RRsetCollectionBase {
public:
/// \brief Constructor.
@@ -1393,26 +1393,11 @@ public:
isc::datasrc::RRsetCollectionBase(updater, rrclass)
{}
- /// \brief Destructor
- virtual ~RRsetCollection() {}
-
/// \brief A wrapper around \c disable() so that it can be used as a
/// public method. \c disable() is protected.
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.");
- }
};
//
@@ -1454,7 +1439,7 @@ public:
virtual ZoneFinder& getFinder() { return (*finder_); }
- virtual isc::datasrc::RRsetCollectionBase& getRRsetCollection() {
+ virtual isc::dns::RRsetCollectionBase& getRRsetCollection() {
if (!rrset_collection_) {
// This is only assigned the first time and remains for the
// lifetime of the DatabaseUpdater.
diff --git a/src/lib/datasrc/rrset_collection_base.h b/src/lib/datasrc/rrset_collection_base.h
index c02df9a..66b5825 100644
--- a/src/lib/datasrc/rrset_collection_base.h
+++ b/src/lib/datasrc/rrset_collection_base.h
@@ -22,14 +22,33 @@
namespace isc {
namespace datasrc {
-/// \brief A forward declaration
-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.
+///
+/// While it is a concrete class to be used along with a \c ZoneUpdater,
+/// specific \c ZoneUpdater implementations may derive from it and add
+/// additional detail. Unless you are implementing a \c ZoneUpdater, you
+/// must not use the constructor directly. Instead use the
+/// \c ZoneUpdater::getRRsetCollection() method to get a reference to
+/// the \c RRsetCollectionBase object for that \c ZoneUpdater. This is
+/// usually a singleton object and the API is designed with this in
+/// mind, because multiple \c RRsetCollectionBase objects cannot be used
+/// at the same time in most kinds of database implementations
+/// (esp. where iterators are in use). Specific \c ZoneUpdaters that can
+/// allow multiple \c RRsetCollection objects may provide additional
+/// API, but that is unspecified here.
+///
+/// There are some restrictions on when an \c RRsetCollection may be
+/// used. Though code may have a reference to an \c RRsetCollection
+/// object, it is not always valid to use it. Implementations of
+/// \c ZoneUpdater may disable an \c RRsetCollection previously returned
+/// by \c ZoneUpdater::getRRsetCollection() after \c commit() is called
+/// on the \c ZoneUpdater. An \c isc::dns::RRsetCollectionError
+/// exception will be thrown if an \c RRsetCollection is used when
+/// disabled. Please see the \c ZoneUpdater methods' documentation for
+/// more detail.
class RRsetCollectionBase : public isc::dns::RRsetCollectionBase {
public:
/// \brief Constructor.
@@ -90,18 +109,18 @@ protected:
/// \brief See \c isc::dns::RRsetCollectionBase::getBeginning() for
/// documentation.
///
- /// \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.
///
- /// \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_;
@@ -109,13 +128,6 @@ private:
bool disabled_;
};
-/// \brief A pointer-like type pointing to an
-/// \c isc::datasrc::RRsetCollectionBase object.
-///
-/// This type is used to handle RRsetCollections in a polymorphic manner
-/// in libdatasrc.
-typedef boost::shared_ptr<isc::datasrc::RRsetCollectionBase> RRsetCollectionPtr;
-
} // end of namespace datasrc
} // end of namespace isc
diff --git a/src/lib/datasrc/tests/database_unittest.cc b/src/lib/datasrc/tests/database_unittest.cc
index c293540..e52d9e9 100644
--- a/src/lib/datasrc/tests/database_unittest.cc
+++ b/src/lib/datasrc/tests/database_unittest.cc
@@ -4447,7 +4447,7 @@ public:
{}
ZoneUpdaterPtr updater;
- isc::datasrc::RRsetCollectionBase& collection;
+ isc::dns::RRsetCollectionBase& collection;
};
TYPED_TEST(RRsetCollectionTest, find) {
@@ -4592,7 +4592,14 @@ TYPED_TEST(RRsetCollectionAndUpdaterTest, updateThrows) {
// Now setup a new updater and call getRRsetCollection() on it.
this->updater_.reset();
this->updater_ = this->client_->getUpdater(this->zname_, false);
- (void) this->updater_->getRRsetCollection();
+
+ // Just call getRRsetCollection() here. The test using .find() is
+ // unnecessary for the purpose of this test case, but we have it to
+ // use the result of getRRsetCollection() and silence some compiler
+ // complaining about ignoring the return value of
+ // getRRsetCollection().
+ EXPECT_FALSE(this->updater_->getRRsetCollection().
+ find(Name("www.example.org"), RRClass::IN(), RRType::MX()));
// addRRset() must throw isc::InvalidOperation here.
EXPECT_THROW(this->updater_->addRRset(*this->rrset_),
@@ -4610,7 +4617,12 @@ TYPED_TEST(RRsetCollectionAndUpdaterTest, updateThrows) {
this->updater_.reset();
this->updater_ = this->client_->getUpdater(this->zname_, false);
this->updater_->addRRset(*this->rrset_);
- (void) this->updater_->getRRsetCollection();
+
+ // Just call getRRsetCollection() here. The .find() is unnecessary,
+ // but we have it to use the result of getRRsetCollection().
+ this->updater_->getRRsetCollection().find(Name("www.example.org"),
+ RRClass::IN(),
+ RRType::MX());
// deleteRRset() must throw isc::InvalidOperation here.
EXPECT_THROW(this->updater_->deleteRRset(*this->rrset_),
@@ -4620,7 +4632,7 @@ TYPED_TEST(RRsetCollectionAndUpdaterTest, updateThrows) {
// Test that using an RRsetCollection after calling commit() on the
// ZoneUpdater throws, as the RRsetCollection is disabled.
TYPED_TEST(RRsetCollectionAndUpdaterTest, useAfterCommitThrows) {
- isc::datasrc::RRsetCollectionBase& collection =
+ isc::dns::RRsetCollectionBase& collection =
this->updater_->getRRsetCollection();
// find() must not throw here.
diff --git a/src/lib/datasrc/tests/master_loader_callbacks_test.cc b/src/lib/datasrc/tests/master_loader_callbacks_test.cc
index dc44461..fb4487a 100644
--- a/src/lib/datasrc/tests/master_loader_callbacks_test.cc
+++ b/src/lib/datasrc/tests/master_loader_callbacks_test.cc
@@ -65,7 +65,7 @@ public:
virtual ZoneFinder& getFinder() {
isc_throw(isc::NotImplemented, "Not to be called in this test");
}
- virtual isc::datasrc::RRsetCollectionBase& getRRsetCollection() {
+ virtual isc::dns::RRsetCollectionBase& getRRsetCollection() {
isc_throw(isc::NotImplemented, "Not to be called in this test");
}
virtual void deleteRRset(const isc::dns::AbstractRRset&) {
diff --git a/src/lib/datasrc/tests/zone_loader_unittest.cc b/src/lib/datasrc/tests/zone_loader_unittest.cc
index 0f44074..4b42185 100644
--- a/src/lib/datasrc/tests/zone_loader_unittest.cc
+++ b/src/lib/datasrc/tests/zone_loader_unittest.cc
@@ -14,6 +14,7 @@
#include <datasrc/zone_loader.h>
#include <datasrc/data_source.h>
+#include <datasrc/rrset_collection_base.h>
#include <datasrc/memory/zone_table_segment.h>
#include <datasrc/memory/memory_client.h>
@@ -163,24 +164,16 @@ public:
RRClass rrclass_;
};
-// Test implementation of RRsetCollectionBase.
+// Test implementation of RRsetCollectionBase. This is currently just a
+// wrapper around \c isc::datasrc::RRsetCollectionBase;
+// \c isc::datasrc::RRsetCollectionBase may become an abstract class in
+// the future.
class TestRRsetCollection : public isc::datasrc::RRsetCollectionBase {
public:
TestRRsetCollection(ZoneUpdater& updater,
const isc::dns::RRClass& rrclass) :
isc::datasrc::RRsetCollectionBase(updater, rrclass)
{}
-
- virtual ~TestRRsetCollection() {}
-
-protected:
- virtual RRsetCollectionBase::IterPtr getBeginning() {
- isc_throw(isc::NotImplemented, "This method is not implemented.");
- }
-
- virtual RRsetCollectionBase::IterPtr getEnd() {
- isc_throw(isc::NotImplemented, "This method is not implemented.");
- }
};
// The updater isn't really correct according to the API. For example,
@@ -197,7 +190,7 @@ public:
virtual ZoneFinder& getFinder() {
return (finder_);
}
- virtual isc::datasrc::RRsetCollectionBase& getRRsetCollection() {
+ virtual isc::dns::RRsetCollectionBase& getRRsetCollection() {
if (!rrset_collection_) {
rrset_collection_.reset(new TestRRsetCollection(*this,
client_->rrclass_));
diff --git a/src/lib/datasrc/zone.h b/src/lib/datasrc/zone.h
index a75f4a0..ca73bb5 100644
--- a/src/lib/datasrc/zone.h
+++ b/src/lib/datasrc/zone.h
@@ -18,10 +18,10 @@
#include <dns/name.h>
#include <dns/rrset.h>
#include <dns/rrtype.h>
+#include <dns/rrset_collection_base.h>
#include <datasrc/exceptions.h>
#include <datasrc/result.h>
-#include <datasrc/rrset_collection_base.h>
#include <utility>
@@ -29,8 +29,6 @@ namespace isc {
namespace datasrc {
/// \brief A forward declaration
-class RRsetCollectionBase;
-
class ZoneFinder;
/// The base class to make updates to a single zone.
@@ -98,7 +96,7 @@ public:
/// Return an RRsetCollection for the updater.
///
/// This method returns an \c RRsetCollection for the updater,
- /// implementing the \c isc::datasrc::RRsetCollectionBase
+ /// implementing the \c isc::dns::RRsetCollectionBase
/// interface. Typically, the returned \c RRsetCollection is a
/// singleton for its \c ZoneUpdater. The returned RRsetCollection
/// object must not be used after its corresponding \c ZoneUpdater
@@ -108,15 +106,51 @@ public:
/// \c ZoneUpdater implementation.
///
/// The behavior of the RRsetCollection is similar to the behavior
- /// of the \c Zonefinder returned by \c getFinder().
+ /// of the \c Zonefinder returned by \c getFinder(). In fact, it's
+ /// redundant in a sense because one can implement the
+ /// \c dns::RRsetCollectionBase interface using an updater and
+ /// \c getFinder() interface (unless it's expected to support zone
+ /// iteration, and the initial implementation of the \c RRsetCollection
+ /// returned by this method doesn't support it). We still provide it
+ /// as an updater's method so it will be easier for an updater
+ /// implementation to customize the \c RRsetCollection implementation,
+ /// and also for making it easy to impose restrictions described below.
+ ///
+ /// Specific data sources may have special restrictions. That's
+ /// especially the case for database-based data sources. Such
+ /// restrictions may also result in limiting the usage of the
+ /// \c RRsetCollection as described in the following paragraphs. A
+ /// specific updater implementation may provide more flexible
+ /// behavior, but applications using this interface must assume
+ /// the most restricted case unless it knows it uses a particular
+ /// specialized updater implementation that loosens specific restrictions.
+ ///
+ /// To summarize the restrictions:
+ /// - An application must not add or delete RRsets after
+ /// \c getRRsetCollection() is called.
+ /// - An application must not use the returned collection from
+ /// \c getRRsetCollection() once \c commit() is called on the updater
+ /// that generates the collection.
+ ///
/// 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.
- virtual isc::datasrc::RRsetCollectionBase& getRRsetCollection() = 0;
+ /// deleting RRsets after \c getRRsetCollection() is called. This is
+ /// because if an iterator of the collection is being used at that time
+ /// the modification to the zone may break an internal assumption of the
+ /// iterator and may result in unexpected behavior. Also, the iterator
+ /// may conceptually hold a "reader lock" of the zone (in an implementation
+ /// dependent manner), which would prevent the addition or deletion,
+ /// surprising the caller (who would normally expect it to succeed).
+ ///
+ /// Implementations of \c ZoneUpdater may disable a previously returned
+ /// \c RRsetCollection after \c commit() is called. This is because
+ /// the returned \c RRsetCollection may internally rely on the conceptual
+ /// transaction of the updater that generates the collection (which would
+ /// be literally the case for database-based data sources), and once
+ /// the transaction is committed anything that relies on it won't be valid.
+ /// 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::dns::RRsetCollectionBase& getRRsetCollection() = 0;
/// Add an RRset to a zone via the updater
///
@@ -166,8 +200,9 @@ 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 (see
+ /// the description of \c getRRsetCollection()). 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
@@ -241,8 +276,9 @@ 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 (see
+ /// the description of \c getRRsetCollection()). 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
diff --git a/src/lib/datasrc/zone_finder.h b/src/lib/datasrc/zone_finder.h
index 6e1cee0..83851f6 100644
--- a/src/lib/datasrc/zone_finder.h
+++ b/src/lib/datasrc/zone_finder.h
@@ -21,7 +21,6 @@
#include <datasrc/exceptions.h>
#include <datasrc/result.h>
-#include <datasrc/rrset_collection_base.h>
#include <utility>
#include <vector>
diff --git a/src/lib/datasrc/zone_loader.cc b/src/lib/datasrc/zone_loader.cc
index 2c57b4f..d0f4a64 100644
--- a/src/lib/datasrc/zone_loader.cc
+++ b/src/lib/datasrc/zone_loader.cc
@@ -20,12 +20,12 @@
#include <datasrc/zone_iterator.h>
#include <datasrc/zone.h>
#include <datasrc/logger.h>
-#include <datasrc/rrset_collection_base.h>
#include <dns/rrset.h>
#include <dns/zone_checker.h>
#include <dns/name.h>
#include <dns/rrclass.h>
+#include <dns/rrset_collection_base.h>
#include <boost/bind.hpp>
@@ -33,6 +33,7 @@
using isc::dns::Name;
using isc::dns::ConstRRsetPtr;
+using isc::dns::RRsetCollectionBase;
using isc::dns::MasterLoader;
using isc::dns::MasterLexer;
diff --git a/src/lib/dns/python/rrset_collection_python_inc.cc b/src/lib/dns/python/rrset_collection_python_inc.cc
index f6eb8a3..baf8ec8 100644
--- a/src/lib/dns/python/rrset_collection_python_inc.cc
+++ b/src/lib/dns/python/rrset_collection_python_inc.cc
@@ -36,6 +36,41 @@ Returns the RRset in the collection that exactly matches the given\n\
name, rrclass and rrtype. If no matching RRset is found, None is\n\
returned.\n\
\n\
+This method's implementations currently are not specified to handle\n\
+RRTypes such as RRSIG and NSEC3. This interface may be refined to\n\
+clarify this point in the future, and perhaps, provide additional API\n\
+for these RRType.\n\
+\n\
+As for RRSIG, there are some fundamental open questions. For example,\n\
+it's not clear whether we want to return all RRSIGs of the given name\n\
+covering any RR types (in which case, we need to figure out how), or\n\
+we need to extend the interface so we can specify the covered type. A\n\
+specific derived implementation may return something if type RRSIG is\n\
+specified, but this is not specified here at the base class level. So,\n\
+for RRSIGs the behavior should be assumed as undefined.\n\
+\n\
+As for NSEC3, it's not clear whether owner names (which included\n\
+hashed labels) are the best choice of search key, because in many\n\
+cases, what the application wants to find is an NSEC3 that has the\n\
+hash of some particular \"normal\" domain names. Also, if the\n\
+underlying implementation encapsulates a single zone, NSEC3 records\n\
+conceptually belong to a separate name space, which may cause\n\
+implementation difficulty.\n\
+\n\
+Behavior with meta types such as ANY and AXFR are also undefined. A\n\
+specific implementation may return something for these. But, unlike\n\
+the case of RRSIGs, these types of RRsets are not expected to be added\n\
+to any implementation of collection in the first place (by the\n\
+definition of \"meta types\"), so querying for such types is\n\
+basically an invalid operation. The API doesn't require\n\
+implementations to check this condition and reject it, so the behavior\n\
+is undefined. This interface will not be refined in future versions\n\
+for these meta types.\n\
+\n\
+Exceptions:\n\
+ RRsetCollectionError if find() results in some implementation-\n\
+ specific error.\n\
+\n\
Parameters:\n\
name (isc.dns.Name) The name of the RRset to search for.\n\
rrtype (isc.dns.RRType) The type of the RRset to search for.\n\
@@ -121,7 +156,7 @@ find(name, rrclass, rrtype) -> isc.dns.RRset\n\
Find a matching RRset in the collection.\n\
\n\
Returns the RRset in the collection that exactly matches the given\n\
-name, rrclass and rrtype. If no matching RRset is found, NULL is\n\
+name, rrclass and rrtype. If no matching RRset is found, None is\n\
returned.\n\
\n\
Parameters:\n\
@@ -129,7 +164,7 @@ Parameters:\n\
rrclass The class of the RRset to search for.\n\
rrtype The type of the RRset to search for.\n\
\n\
-Return Value(s): The RRset if found, NULL otherwise.\n\
+Return Value(s): The RRset if found, None otherwise.\n\
";
// Modifications
diff --git a/src/lib/dns/rrset_collection_base.h b/src/lib/dns/rrset_collection_base.h
index 7ccf7b5..f7c9b6b 100644
--- a/src/lib/dns/rrset_collection_base.h
+++ b/src/lib/dns/rrset_collection_base.h
@@ -27,7 +27,7 @@ namespace dns {
/// \brief Error during RRsetCollectionBase find() operation
///
-/// This exception is thrown when an calling implementation of
+/// This exception is thrown when calling an implementation of
/// \c RRsetCollectionBase::find() results in an error which is not due
/// to unmatched data, but because of some other underlying error
/// condition.
@@ -58,13 +58,37 @@ public:
/// is found, \c NULL is returned.
///
/// This method's implementations currently are not specified to
- /// handle \c RRTypes such as RRSIG and NSEC3. RRSIGs are attached
- /// to their corresponding \c RRset and it is not straightforward to
- /// search for them. Searching for RRSIGs will return \c false
- /// always. Support for RRSIGs may be added in the future.
+ /// handle \c RRTypes such as RRSIG and NSEC3. This interface may be
+ /// refined to clarify this point in the future, and perhaps, provide
+ /// additional API for these RRType.
///
- /// Non-concrete types such as ANY and AXFR are unsupported and will
- /// return \c false always.
+ /// As for RRSIG, there are some fundamental open questions. For
+ /// example, it's not clear whether we want to return all RRSIGs of
+ /// the given name covering any RR types (in which case, we need to
+ /// figure out how), or we need to extend the interface so we can
+ /// specify the covered type. A specific derived implementation may
+ /// return something if type RRSIG is specified, but this is not
+ /// specified here at the base class level. So, for RRSIGs the
+ /// behavior should be assumed as undefined.
+ ///
+ /// As for NSEC3, it's not clear whether owner names (which included
+ /// hashed labels) are the best choice of search key, because in many
+ /// cases, what the application wants to find is an NSEC3 that has the
+ /// hash of some particular "normal" domain names. Also, if the underlying
+ /// implementation encapsulates a single zone, NSEC3 records conceptually
+ /// belong to a separate name space, which may cause implementation
+ /// difficulty.
+ ///
+ /// Behavior with meta types such as ANY and AXFR are also
+ /// undefined. A specific implementation may return something for
+ /// these. But, unlike the case of RRSIGs, these types of RRsets
+ /// are not expected to be added to any implementation of
+ /// collection in the first place (by the definition of "meta
+ /// types"), so querying for such types is basically an invalid
+ /// operation. The API doesn't require implementations to check
+ /// this condition and reject it, so the behavior is
+ /// undefined. This interface will not be refined in future
+ /// versions for these meta types.
///
/// \throw RRsetCollectionError if find() results in some
/// implementation-specific error.
diff --git a/src/lib/python/isc/datasrc/updater_inc.cc b/src/lib/python/isc/datasrc/updater_inc.cc
index f040f85..87c8158 100644
--- a/src/lib/python/isc/datasrc/updater_inc.cc
+++ b/src/lib/python/isc/datasrc/updater_inc.cc
@@ -187,10 +187,9 @@ Exceptions:\n\
\n\
";
-// Modifications
-// - isc.datasrc.RRsetCollectionBase => isc.dns.RRsetCollectionBase
-// (in the Python wrapper, the former is completely invisible)
-// - remove other reference to isc.datasrc.RRsetCollectionBase
+// Modifications:
+// - remove reference to isc.datasrc.RRsetCollectionBase (hidden for Python
+// wrapper)
const char* const ZoneUpdater_getRRsetCollection_doc = "\
get_rrset_collection() -> isc.dns.RRsetCollectionBase \n\
\n\
@@ -206,10 +205,46 @@ RRsetCollection returned has a behavior dependent on the ZoneUpdater\n\
implementation.\n\
\n\
The behavior of the RRsetCollection is similar to the behavior of the\n\
-Zonefinder returned by get_finder(). Implementations of ZoneUpdater\n\
-may not allow adding or deleting RRsets after get_rrset_collection()\n\
-is called. Implementations of ZoneUpdater may disable a previously\n\
-returned RRsetCollection after commit() is called. If an\n\
+Zonefinder returned by get_finder(). In fact, it's redundant in a\n\
+sense because one can implement the dns.RRsetCollectionBase interface\n\
+using an updater and get_finder() interface (unless it's expected to\n\
+support zone iteration, and the initial implementation of the\n\
+RRsetCollection returned by this method doesn't support it). We\n\
+still provide it as an updater's method so it will be easier for an\n\
+updater implementation to customize the RRsetCollection\n\
+implementation, and also for making it easy to impose restrictions\n\
+described below.\n\
+\n\
+Specific data sources may have special restrictions. That's especially\n\
+the case for database-based data sources. Such restrictions may also\n\
+result in limiting the usage of the RRsetCollection as described in\n\
+the following paragraphs. A specific updater implementation may\n\
+provide more flexible behavior, but applications using this interface\n\
+must assume the most restricted case unless it knows it uses a\n\
+particular specialized updater implementation that loosens specific\n\
+restrictions.\n\
+\n\
+- An application must not add or delete RRsets after\n\
+ get_rrset_collection() is called.\n\
+- An application must not use the returned collection from\n\
+ get_rrset_collection() once commit() is called on the updater that\n\
+ generates the collection.\n\
+\n\
+Implementations of ZoneUpdater may not allow adding or deleting RRsets\n\
+after get_rrset_collection() is called. This is because if an\n\
+iterator of the collection is being used at that time the modification\n\
+to the zone may break an internal assumption of the iterator and may\n\
+result in unexpected behavior. Also, the iterator may conceptually\n\
+hold a \"reader lock\" of the zone (in an implementation dependent\n\
+manner), which would prevent the addition or deletion, surprising the\n\
+caller (who would normally expect it to succeed).\n\
+\n\
+Implementations of ZoneUpdater may disable a previously returned\n\
+RRsetCollection after commit() is called. This is because the returned\n\
+RRsetCollection may internally rely on the conceptual transaction of\n\
+the updater that generates the collection (which would be literally\n\
+the case for database-based data sources), and once the transaction is\n\
+committed anything that relies on it won't be valid. If an\n\
RRsetCollection is disabled, using methods such as find() and using\n\
its iterator would cause an exception to be thrown.\n\
\n\
More information about the bind10-changes
mailing list