Commit 36db2f89 authored by Michal 'vorner' Vaner's avatar Michal 'vorner' Vaner
Browse files

[1331] A documentation refinement

parent 573abf93
......@@ -265,6 +265,21 @@ public:
/// In such cases this method will result in an \c isc::NotImplemented
/// exception unconditionally or when \c replace is false).
///
/// If \c journaling is true, the data source should store a journal
/// of changes. These can be used later on by, for example, IXFR-out.
/// However, the parameter is a hint only. It might be unable to store
/// them and they would be silently discarded. Or it might need to
/// store them no matter what (for example a git-based data source would
/// store journal implicitly). When the \c journaling is true, it might
/// require that the following update be formated as IXFR transfer
/// (SOA to be removed, bunch of RRs to be removed, SOA to be added,
/// bunch of RRs to be added, and possibly repeated). If it is false, it
/// must not require so.
///
/// We don't support erasing the whole zone (by replace being true) and
/// saving a journal at the same time. In such situation, BadValue is
/// thrown.
///
/// \note To avoid throwing the exception accidentally with a lazy
/// implementation, we still keep this method pure virtual without
/// an implementation. All derived classes must explicitly define this
......@@ -275,13 +290,12 @@ public:
/// \exception DataSourceError Internal error in the underlying data
/// source.
/// \exception std::bad_alloc Resource allocation failure.
/// \exception BadValue if both replace and journaling are true.
///
/// \param name The zone name to be updated
/// \param replace Whether to delete existing RRs before making updates
/// \param journaling The zone updater should store a journal of the
/// changes (such journal can be used, for example, by IXFR-out).
/// This is a hint only (the updater might be unable to store or
/// not store the journal).
/// changes.
///
/// \return A pointer to the updater; it will be NULL if the specified
/// zone isn't found.
......
......@@ -438,6 +438,10 @@ public:
/// calls after \c commit() the implementation must throw a
/// \c DataSourceError exception.
///
/// If journaling was requested when getting this updater, it might reject
/// to add the RRset if the squence doesn't look like and IXFR. In such
/// such case isc::BadValue is thrown.
///
/// \todo As noted above we may have to revisit the design details as we
/// gain experiences:
///
......@@ -454,6 +458,8 @@ public:
///
/// \exception DataSourceError Called after \c commit(), RRset is invalid
/// (see above), internal data source error
/// \exception isc::BadValue Journaling is enabled and the current RRset
/// doesn't fit into the IXFR sequence (see above).
/// \exception std::bad_alloc Resource allocation failure
///
/// \param rrset The RRset to be added
......@@ -503,6 +509,10 @@ public:
/// calls after \c commit() the implementation must throw a
/// \c DataSourceError exception.
///
/// If journaling was requested when getting this updater, it might reject
/// to add the RRset if the squence doesn't look like and IXFR. In such
/// such case isc::BadValue is thrown.
///
/// \todo As noted above we may have to revisit the design details as we
/// gain experiences:
///
......@@ -520,6 +530,8 @@ public:
///
/// \exception DataSourceError Called after \c commit(), RRset is invalid
/// (see above), internal data source error
/// \exception isc::BadValue Journaling is enabled and the current RRset
/// doesn't fit into the IXFR sequence (see above).
/// \exception std::bad_alloc Resource allocation failure
///
/// \param rrset The RRset to be deleted
......
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