Commit 9ab6902f authored by JINMEI Tatuya's avatar JINMEI Tatuya
Browse files

[1332] added documentation reagrding ZoneJournalReader.

parent 8c57956e
......@@ -312,6 +312,51 @@ public:
bool replace, bool journaling = false)
const = 0;
/// Return a journal reader to retrieve differences of a zone.
///
/// A derived version of this method creates a concrete
/// \c ZoneJournalReader object specific to the underlying data source
/// for the specified name of zone and differences between the versions
/// specified by the beginning and ending serials of the corresponding
/// SOA RRs.
/// The RR class of the zone is the one that the client is expected to
/// handle (see the detailed description of this class).
///
/// Note that the SOA serials are compared by the semantics of the serial
/// number arithmetic. So, for example, \c begin_serial can be larger than
/// \c end_serial as bare unsigned integers. The underlying data source
/// implementation is assumed to keep truck of sufficient history to
/// identify (if exist) the corresponding difference between the specified
/// versions.
///
/// This method returns the result as a pair of a result code and
/// a pointer to a \c ZoneJournalReader object. On success, the result
/// code is \c SUCCESS and the pointer must be non NULL; otherwise
/// the result code is something other than \c SUCCESS and the pinter
/// must be NULL.
///
/// If the specified zone is not found in the data source, the result
/// code is \c NO_SUCH_ZONE.
/// Otherwise, if specified range of difference for the zone is not found
/// in the data source, the result code is \c NO_SUCH_VERSION.
///
/// Handling differences is an optional feature of data source.
/// If the underlying data source does not support difference handling,
/// this method for that type of data source can throw an exception of
/// class \c NotImplemented.
///
/// \exception NotImplemented The data source does not support differences.
/// \exception DataSourceError Other operational errors at the data source
/// level.
///
/// \param zone The name of the zone for which the difference should be
/// retrieved.
/// \param begin_serial The SOA serial of the beginning version of the
/// differences.
/// \param end_serial The SOA serial of the ending version of the
/// differences.
///
/// \return A pair of result code and a pointer to \c ZoneJournalReader.
virtual std::pair<ZoneJournalReader::Result, ZoneJournalReaderPtr>
getJournalReader(const isc::dns::Name& zone, uint32_t begin_serial,
uint32_t end_serial) const = 0;
......
......@@ -1186,7 +1186,7 @@ DatabaseClient::getJournalReader(const isc::dns::Name& zone,
return (ret);
} catch (const NoSuchSerial&) {
return (pair<ZoneJournalReader::Result, ZoneJournalReaderPtr>(
ZoneJournalReader::NO_SUCH_SERIAL,
ZoneJournalReader::NO_SUCH_VERSION,
ZoneJournalReaderPtr()));
}
}
......
......@@ -3161,10 +3161,10 @@ TYPED_TEST(DatabaseClientTest, readJournalForNoRange) {
makeSimpleDiff(*this->client_, this->zname_, this->qclass_, this->soa_);
// The specified range does not exist in the diff storage. The factory
// method should result in NO_SUCH_SERIAL
// method should result in NO_SUCH_VERSION
pair<ZoneJournalReader::Result, ZoneJournalReaderPtr> result =
this->client_->getJournalReader(this->zname_, 1200, 1235);
EXPECT_EQ(ZoneJournalReader::NO_SUCH_SERIAL, result.first);
EXPECT_EQ(ZoneJournalReader::NO_SUCH_VERSION, result.first);
EXPECT_FALSE(result.second);
}
......
......@@ -560,14 +560,27 @@ public:
/// \brief A pointer-like type pointing to a \c ZoneUpdater object.
typedef boost::shared_ptr<ZoneUpdater> ZoneUpdaterPtr;
/// The base class to retrieve differences between two versions of a zone.
/// The base class for retrieving differences between two versions of a zone.
///
/// On construction, each derived class object will internally set up
/// retrieving sequences of differences between two specific version of
/// a specific zone managed in a particular data source. So the constructor
/// of a derived class would normally take parameters to identify the zone
/// and the two versions for which the differences should be retrieved.
/// See \c DataSourceClient::getJournalReader for more concrete details
/// used in this API.
///
/// Once constructed, an object of this class will act like an iterator
/// over the sequences. Every time the \c getNextDiff() method is called
/// it returns one element of the differences in the form of an \c RRset
/// until it reaches the end of the entire sequences.
class ZoneJournalReader {
public:
/// TBD: describe this
/// Result codes used by a factory method for \c ZoneJournalReader
enum Result {
SUCCESS,
NO_SUCH_ZONE,
NO_SUCH_SERIAL
SUCCESS, ///< A \c ZoneJournalReader object successfully created
NO_SUCH_ZONE, ///< Specified zone does not exist in the data source
NO_SUCH_VERSION ///< Specified versions do not exist in the diff storage
};
protected:
......@@ -581,6 +594,58 @@ public:
/// The destructor
virtual ~ZoneJournalReader() {}
/// Return the next difference RR of difference sequences.
///
/// In this API, the difference between two versions of a zone is
/// conceptually represented as IXFR-style difference sequences:
/// Each difference sequence is a sequence of RRs: an older version of
/// SOA (to be deleted), zero or more other deleted RRs, the
/// post-transaction SOA (to be added), and zero or more other
/// added RRs. (Note, however, that the underlying data source
/// implementation may or may not represent the difference in
/// straightforward realization of this concept. The mapping between
/// the conceptual difference and the actual implementation is hidden
/// in each derived class).
///
/// This method provides an application with a higher level interface
/// to retrieve the difference along with the conceptual model: the
/// \c ZoneJournalReader object iterates over the entire sequences
/// from the beginning SOA (which is to be deleted) to one of the
/// added RR of with the ending SOA, and each call to this method returns
/// one RR in the form of an \c RRset that contains exactly one RDATA
/// in the order of the sequences.
///
/// Note that the ordering of the sequences specifies the semantics of
/// each difference: add or delete. For example, the first RR is to
/// be deleted, and the last RR is to be added. So the return value
/// of this method does not explicitly indicate whether the RR is to be
/// added or deleted.
///
/// This method ensures the returned \c RRset represents an RR, that is,
/// it contains exactly one RDATA. However, it does not necessarily
/// ensure that the resulting sequences are in the form of IXFR-style.
/// For example, the first RR is supposed to be an SOA, and it should
/// normally be the case, but this interface does not necessarily require
/// the derived class implementation ensure this. Normally the
/// differences are expected to be stored using this API (via a
/// \c ZoneUpdater object), and as long as that is the case and the
/// underlying implementation follows the requirement of the API, the
/// result of this method should be a valid IXFR-style sequences.
/// So this API does not mandate the almost redundant check as part of
/// the interface. If the application needs to make it sure 100%, it
/// must check the resulting sequence itself.
///
/// Once the object reaches the end of the sequences, this method returns
/// \c Null. Any subsequent call will result in an exception of
/// class \c InvalidOperation.
///
/// \exception InvalidOperation The method is called beyond the end of
/// the difference sequences.
/// \exception DataSourceError Underlying data is broken and the RR
/// cannot be created or other low level data source error.
///
/// \return An \c RRset that contains one RDATA corresponding to the
/// next difference in the sequences.
virtual isc::dns::ConstRRsetPtr getNextDiff() = 0;
};
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment