Commit feae0b93 authored by JINMEI Tatuya's avatar JINMEI Tatuya
Browse files

[trac1060] overall documentation updates, typo/wording fixing.

parent 8f5f77f8
......@@ -81,8 +81,8 @@ private:
/// This method may throw a exception because its underlying methods may
/// throw exceptions.
///
/// \param zone The ZoneFinder wherein the additional data to the query is bo be
/// found.
/// \param zone The ZoneFinder through which the additional data for the
/// query is to be found.
/// \param rrset The RRset (i.e., NS or MX rrset) which require additional
/// processing.
void getAdditional(const isc::datasrc::ZoneFinder& zone,
......@@ -100,7 +100,8 @@ private:
/// The glue records must exactly match the name in the NS RDATA, without
/// CNAME or wildcard processing.
///
/// \param zone The \c ZoneFinder wherein the address records is to be found.
/// \param zone The \c ZoneFinder through which the address records is to
/// be found.
/// \param qname The name in rrset RDATA.
/// \param options The search options.
void findAddrs(const isc::datasrc::ZoneFinder& zone,
......@@ -108,10 +109,10 @@ private:
const isc::datasrc::ZoneFinder::FindOptions options
= isc::datasrc::ZoneFinder::FIND_DEFAULT) const;
/// \brief Look up \c ZoneFinder's NS and address records for the NS RDATA
/// (domain name) for authoritative answer.
/// \brief Look up a zone's NS RRset and their address records for an
/// authoritative answer.
///
/// On returning an authoritative answer, insert the \c ZoneFinder's NS into the
/// On returning an authoritative answer, insert a zone's NS into the
/// authority section and AAAA/A RRs of each of the NS RDATA into the
/// additional section.
///
......@@ -124,8 +125,8 @@ private:
/// include AAAA/A RRs under a zone cut in additional section. (BIND 9
/// excludes under-cut RRs; NSD include them.)
///
/// \param zone The \c ZoneFinder wherein the additional data to the query is to
/// be found.
/// \param zone The \c ZoneFinder through which the NS and additional data
/// for the query are to be found.
void getAuthAdditional(const isc::datasrc::ZoneFinder& zone) const;
public:
......
......@@ -95,7 +95,7 @@ const char* const other_zone_rrs =
// This is a mock Zone class for testing.
// It is a derived class of ZoneFinder for the convenient of tests.
// Its find() method emulates the common behavior of protocol compliant
// zone classes, but simplifies some minor cases and also supports broken
// ZoneFinder classes, but simplifies some minor cases and also supports broken
// behavior.
// For simplicity, most names are assumed to be "in zone"; there's only
// one zone cut at the point of name "delegation.example.com".
......
......@@ -20,16 +20,56 @@
namespace isc {
namespace datasrc {
/// \brief TBD
/// \brief The base class of data source clients.
///
/// naming note: somehow redundant with the namespace of "datasrc", but
/// namespaces are often omitted with 'using' directives. In that case
/// "Client" would be too generic. So we name it with some redundancy.
/// On the other hand, concrete derived classes are generally not expected
/// to be referenced directly from other modules and applications, so
/// we'll give them more concise names such as InMemoryClient.
/// This is an abstract base class that defines the common interface for
/// various types of data source clients. A data source client is a top level
/// access point to a data source, allowing various operations on the data
/// source such as lookups, traversing or updates. The client class itself
/// has limited focus and delegates the responsibility for these specific
/// operations to other classes; in general methods of this class act as
/// factories of these other classes.
///
/// This class is not copyable.
/// The following derived classes are currently (expected to be) provided:
/// - \c InMemoryClient: A client of a conceptual data source that stores
/// all necessary data in memory for faster lookups
/// - \c DatabaseClient: A client that uses a real database backend (such as
/// an SQL database). It would internally hold a connection to the underlying
/// database system.
///
/// \note It is intentional that while the term these derived classes don't
/// contain "DataSource" unlike their base class. It's also noteworthy
/// that the naming of the base class is somewhat redundant because the
/// namespace \c datasrc would indicate that it's related to a data source.
/// The redundant naming comes from the observation that namespaces are
/// often omitted with \c using directives, in which case "Client"
/// would be too generic. On the other hand, concrete derived classes are
/// generally not expected to be referenced directly from other modules and
/// applications, so we'll give them more concise names such as InMemoryClient.
///
/// A single \c DataSourceClient object is expected to handle only a single
/// RR class even if the underlying data source contains records for multiple
/// RR classes. Likewise, (when we support views) a \c DataSourceClient
/// object is expected to handle only a single view.
///
/// If the application uses multiple threads, each thread will need to
/// create and use a separate DataSourceClient. This is because some
/// database backend doesn't allow multiple threads to share the same
/// connection to the database.
///
/// \note For a client using an in memory backend, this may result in
/// having a multiple copies of the same data in memory, increasing the
/// memory footprint substantially. Depending on how to support multiple
/// CPU cores for concurrent lookups on the same single data source (which
/// is not fully fixed yet, and for which multiple threads may be used),
/// this design may have to be revisited.
///
/// This class (and therefore its derived classes) are not copyable.
/// This is because the derived classes would generally contain attributes
/// that are not easy to copy (such as a large size of in memory data or a
/// network connection to a database server). In order to avoid a surprising
/// disruption with a naive copy it's prohibited explicitly. For the expected
/// usage of the client classes the restriction should be acceptable.
///
/// \todo This class is not complete. It needs more factory methods, for
/// accessing the whole zone, updating it, loading it, etc.
......@@ -65,10 +105,13 @@ public:
protected:
/// Default constructor.
///
/// \exception
/// This constructor internally involves resource allocation, and if
/// it fails, a corresponding standard exception will be thrown.
/// It never throws an exception otherwise.
/// This is intentionally defined as protected as this base class
/// should never be instantiated directly.
///
/// The constructor of a concrete derived class may throw an exception.
/// This interface does not specify which exceptions can happen (at least
/// at this moment), and the caller should expect any type of exception
/// and react accordingly.
DataSourceClient() {}
public:
......@@ -76,21 +119,24 @@ public:
virtual ~DataSourceClient() {}
//@}
/// Find a \c Zone that best matches the given name via this client.
/// Returns a \c ZoneFinder for a zone that best matches the given name.
///
/// It searches the internal storage for a \c Zone that gives the
/// longest match against \c name, and returns the result in the
/// form of a \c FindResult object as follows:
/// A concrete derived version of this method gets access to its backend
/// data source to search for a zone whose origin gives the longest match
/// against \c name. It returns the search result in the form of a
/// \c FindResult object as follows:
/// - \c code: The result code of the operation.
/// - \c result::SUCCESS: A zone that gives an exact match
/// is found
/// - \c result::SUCCESS: A zone that gives an exact match is found
/// - \c result::PARTIALMATCH: A zone whose origin is a
/// super domain of \c name is found (but there is no exact match)
/// - \c result::NOTFOUND: For all other cases.
/// - \c zone: Pointer to the found \c ZoneFinder object if one
/// is found; otherwise \c NULL.
/// - \c zone_finder: Pointer to a \c ZoneFinder object for the found zone
/// if one is found; otherwise \c NULL.
///
/// This method never throws an exception.
/// A specific derived version of this method may throw an exception.
/// This interface does not specify which exceptions can happen (at least
/// at this moment), and the caller should expect any type of exception
/// and react accordingly.
///
/// \param name A domain name for which the search is performed.
/// \return A \c FindResult object enclosing the search result (see above).
......
......@@ -183,34 +183,33 @@ private:
//@}
};
/// \brief A data source that uses in memory dedicated backend.
/// \brief A data source client that holds all necessary data in memory.
///
/// The \c InMemoryClient class represents a data source and provides a
/// basic interface to help DNS lookup processing. For a given domain
/// name, its \c findZone() method searches the in memory dedicated backend
/// for the zone that gives a longest match against that name.
/// The \c InMemoryClient class provides an access to a conceptual data
/// source that maintains all necessary data in a memory image, thereby
/// allowing much faster lookups. The in memory data is a copy of some
/// real physical source - in the current implementation a list of zones
/// are populated as a result of \c addZone() calls; zone data is given
/// in a standard master file (but there's a plan to use database backends
/// as a source of the in memory data).
///
/// The in memory dedicated backend are assumed to be of the same RR class,
/// but the \c InMemoryClient class does not enforce the assumption through
/// Although every data source client is assumed to be of the same RR class,
/// the \c InMemoryClient class does not enforce the assumption through
/// its interface.
/// For example, the \c addZone() method does not check if the new zone is of
/// the same RR class as that of the others already in the dedicated backend.
/// the same RR class as that of the others already in memory.
/// It is caller's responsibility to ensure this assumption.
///
/// <b>Notes to developer:</b>
///
/// For now, we don't make it a derived class of AbstractDataSrc because the
/// interface is so different (we'll eventually consider this as part of the
/// generalization work).
///
/// The addZone() method takes a (Boost) shared pointer because it would be
/// inconvenient to require the caller to maintain the ownership of zones,
/// while it wouldn't be safe to delete unnecessary zones inside the dedicated
/// backend.
///
/// The findZone() method takes a domain name and returns the best matching \c
/// MemoryZone in the form of (Boost) shared pointer, so that it can provide
/// the general interface for all data sources.
/// The findZone() method takes a domain name and returns the best matching
/// \c MemoryZoneFinder in the form of (Boost) shared pointer, so that it can
/// provide the general interface for all data sources.
class InMemoryClient : public DataSourceClient {
public:
///
......@@ -229,51 +228,37 @@ public:
~InMemoryClient();
//@}
/// Return the number of zones stored in the data source.
/// Return the number of zones stored in the client.
///
/// This method never throws an exception.
///
/// \return The number of zones stored in the data source.
/// \return The number of zones stored in the client.
unsigned int getZoneCount() const;
/// Add a \c Zone to the \c InMemoryClient.
/// Add a zone (in the form of \c ZoneFinder) to the \c InMemoryClient.
///
/// \c Zone must not be associated with a NULL pointer; otherwise
/// \c zone must not be associated with a NULL pointer; otherwise
/// an exception of class \c InvalidParameter will be thrown.
/// If internal resource allocation fails, a corresponding standard
/// exception will be thrown.
/// This method never throws an exception otherwise.
///
/// \param zone A \c Zone object to be added.
/// \param zone A \c ZoneFinder object to be added.
/// \return \c result::SUCCESS If the zone is successfully
/// added to the memory data source.
/// added to the client.
/// \return \c result::EXIST The memory data source already
/// stores a zone that has the same origin.
result::Result addZone(ZoneFinderPtr zone);
/// Find a \c Zone that best matches the given name in the \c InMemoryClient.
///
/// It searches the internal storage for a \c Zone that gives the
/// longest match against \c name, and returns the result in the
/// form of a \c FindResult object as follows:
/// - \c code: The result code of the operation.
/// - \c result::SUCCESS: A zone that gives an exact match
/// is found
/// - \c result::PARTIALMATCH: A zone whose origin is a
/// super domain of \c name is found (but there is no exact match)
/// - \c result::NOTFOUND: For all other cases.
/// - \c zone: A "Boost" shared pointer to the found \c Zone object if one
/// is found; otherwise \c NULL.
///
/// This method never throws an exception.
/// Returns a \c ZoneFinder for a zone that best matches the given name.
///
/// \param name A domain name for which the search is performed.
/// \return A \c FindResult object enclosing the search result (see above).
/// This derived version of the method never throws an exception.
/// For other details see \c DataSourceClient::findZone().
virtual FindResult findZone(const isc::dns::Name& name) const;
private:
// TODO: Do we still need the PImpl if nobody should manipulate this class
// directly any more (it should be handled trough DataSourceClient)?
// directly any more (it should be handled through DataSourceClient)?
class InMemoryClientImpl;
InMemoryClientImpl* impl_;
};
......
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