[2433] Merge remote-tracking branch 'origin/trac2432' into trac2433

src/lib/dns/Makefile.am

@@ -172,6 +172,8 @@ libdns___include_HEADERS = \
 	rdata.h \
 	rrparamregistry.h \
 	rrset.h \
+	rrset_collection_base.h \
+	rrset_collection.h \
 	rrttl.h \
 	tsigkey.h
 # Purposely not installing these headers:

src/lib/dns/rrset_collection.cc

@@ -68,6 +68,19 @@ RRsetCollection::RRsetCollection(const char* filename, const Name& origin,
     loader.load();
 }
 
+RRsetCollection::RRsetCollection(std::istream& input_stream, const Name& origin,
+                                 const RRClass& rrclass)
+{
+    MasterLoaderCallbacks callbacks
+        (boost::bind(&RRsetCollection::loaderCallback, this, _1, _2, _3),
+         boost::bind(&RRsetCollection::loaderCallback, this, _1, _2, _3));
+    MasterLoader loader(input_stream, origin, rrclass, callbacks,
+                        boost::bind(&RRsetCollection::addRRset,
+                                    this, _1, _2, _3, _4, _5),
+                        MasterLoader::DEFAULT);
+    loader.load();
+}
+
 const AbstractRRset*
 RRsetCollection::find(const Name& name, const RRType& rrtype,
                       const RRClass& rrclass) const {

src/lib/dns/rrset_collection.h

@@ -31,8 +31,7 @@ namespace dns {
 class RRsetCollection : public RRsetCollectionBase {
 public:
     /// \brief Constructor.
-    RRsetCollection()
-    {}
+    RRsetCollection() {}
 
     /// \brief Constructor.
     ///
@@ -44,15 +43,36 @@ public:
     ///
     /// \param filename Name of a file containing a collection of RRs in
     /// the master file format (which may or may not form a valid zone).
+    /// \param origin The zone origin.
+    /// \param rrclass The zone class.
     RRsetCollection(const char* filename, const isc::dns::Name& origin,
                     const isc::dns::RRClass& rrclass);
 
+    /// \brief Constructor.
+    ///
+    /// This constructor is similar to the previous one, but instead of
+    /// taking a filename to load a zone from, it takes an input
+    /// stream. The constructor throws MasterLoaderError if there is an
+    /// error during loading.
+    ///
+    /// \param input_stream The input stream to load from.
+    /// \param origin The zone origin.
+    /// \param rrclass The zone class.
+    RRsetCollection(std::istream& input_stream, const isc::dns::Name& origin,
+                    const isc::dns::RRClass& rrclass);
+
+    /// \brief Destructor
+    virtual ~RRsetCollection() {}
+
     /// \brief Add an RRset to the collection.
     ///
     /// Does not do any validation whether \c rrset belongs to a
-    /// particular zone or not. It throws an \c isc::InvalidParameter
-    /// exception if an rrset with the same class, type and name already
-    /// exists.
+    /// particular zone or not. A reference to \c rrset is taken in an
+    /// internally managed \c shared_ptr, so even if the caller's
+    /// \c RRsetPtr is destroyed, the RRset it wrapped is still alive
+    /// and managed by the \c RRsetCollection. It throws an
+    /// \c isc::InvalidParameter exception if an rrset with the same
+    /// class, type and name already exists.
     void addRRset(isc::dns::RRsetPtr rrset);
 
     /// \brief Remove an RRset from the collection.

src/lib/dns/rrset_collection_base.h

@@ -50,24 +50,61 @@ public:
     /// \returns A pointer to the RRset if found, \c NULL otherwise.
     virtual const isc::dns::AbstractRRset* find
         (const isc::dns::Name& name, const isc::dns::RRType& rrtype,
-	 const isc::dns::RRClass& rrclass)
+         const isc::dns::RRClass& rrclass)
         const = 0;
 
+    /// \brief Destructor
+    virtual ~RRsetCollectionBase() {}
+
 protected:
     class Iter; // forward declaration
+
+    /// \brief Wraps Iter with a reference count.
     typedef boost::shared_ptr<Iter> IterPtr;
 
+    /// \brief A helper iterator interface for \c RRsetCollectionBase.
+    ///
+    /// This is a protected iterator class that is a helper interface
+    /// used by the public iterator.  Derived classes of
+    /// \c RRsetCollectionBase are supposed to implement this class and
+    /// the \c getBeginning() and \c getEnd() methods, so that the
+    /// public interator interface can be provided. This is a forward
+    /// iterator only.
     class Iter {
     public:
+        /// \brief Returns the \c AbstractRRset currently pointed to by
+        /// the iterator.
         virtual const isc::dns::AbstractRRset& getValue() = 0;
+
+        /// \brief Returns an \c IterPtr wrapping an Iter pointing to
+        /// the next \c AbstractRRset in sequence in the collection.
         virtual IterPtr getNext() = 0;
+
+        /// \brief Check if another iterator is equal to this one.
+        ///
+        /// Returns \c true if this iterator is equal to \c other,
+        /// \c false otherwise. Note that if \c other is not the same
+        /// type as \c this, or cannot be compared meaningfully, the
+        /// method must return \c false.
+        ///
+        /// \param other The other iterator to compare against.
+        /// \returns \c true if equal, \c false otherwise.
         virtual bool equals(Iter& other) = 0;
     };
 
+    /// \brief Returns an \c IterPtr wrapping an Iter pointing to the
+    /// beginning of the collection.
     virtual IterPtr getBeginning() = 0;
+
+    /// \brief Returns an \c IterPtr wrapping an Iter pointing past the
+    /// end of the collection.
     virtual IterPtr getEnd() = 0;
 
 public:
+    /// \brief A forward \c std::iterator for \c RRsetCollectionBase.
+    ///
+    /// It behaves like a \c std::iterator forward iterator, so please
+    /// see its documentation for usage.
     class iterator : std::iterator<std::forward_iterator_tag,
                                    const isc::dns::AbstractRRset>
     {
@@ -103,10 +140,14 @@ public:
         IterPtr iter_;
     };
 
+    /// \brief Returns an iterator pointing to the beginning of the
+    /// collection.
     iterator begin() {
       return iterator(getBeginning());
     }
 
+    /// \brief Returns an iterator pointing past the end of the
+    /// collection.
     iterator end() {
       return iterator(getEnd());
     }

src/lib/dns/tests/rrset_collection_unittest.cc

@@ -19,6 +19,7 @@
 #include <gtest/gtest.h>
 
 #include <list>
+#include <fstream>
 
 using namespace isc::dns;
 using namespace isc::dns::rdata;
@@ -39,6 +40,21 @@ public:
     RRsetCollection collection;
 };
 
+TEST_F(RRsetCollectionTest, istreamConstructor) {
+    std::ifstream fs(TEST_DATA_SRCDIR "/example.org");
+    RRsetCollection collection2(fs, origin, rrclass);
+
+    RRsetCollectionBase::iterator iter = collection.begin();
+    RRsetCollectionBase::iterator iter2 = collection2.begin();
+    while (iter != collection.end()) {
+         EXPECT_TRUE(iter2 != collection2.end());
+         EXPECT_EQ((*iter).toText(), (*iter2).toText());
+         ++iter;
+         ++iter2;
+    }
+    EXPECT_TRUE(iter2 == collection2.end());
+}
+
 TEST_F(RRsetCollectionTest, findBase) {
     // Test the find() that returns isc::dns::AbstractRRset*
     const AbstractRRset* rrset = collection.find(Name("www.example.org"),