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: ...@@ -265,6 +265,21 @@ public:
/// In such cases this method will result in an \c isc::NotImplemented /// In such cases this method will result in an \c isc::NotImplemented
/// exception unconditionally or when \c replace is false). /// 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 /// \note To avoid throwing the exception accidentally with a lazy
/// implementation, we still keep this method pure virtual without /// implementation, we still keep this method pure virtual without
/// an implementation. All derived classes must explicitly define this /// an implementation. All derived classes must explicitly define this
...@@ -275,13 +290,12 @@ public: ...@@ -275,13 +290,12 @@ public:
/// \exception DataSourceError Internal error in the underlying data /// \exception DataSourceError Internal error in the underlying data
/// source. /// source.
/// \exception std::bad_alloc Resource allocation failure. /// \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 name The zone name to be updated
/// \param replace Whether to delete existing RRs before making updates /// \param replace Whether to delete existing RRs before making updates
/// \param journaling The zone updater should store a journal of the /// \param journaling The zone updater should store a journal of the
/// changes (such journal can be used, for example, by IXFR-out). /// changes.
/// This is a hint only (the updater might be unable to store or
/// not store the journal).
/// ///
/// \return A pointer to the updater; it will be NULL if the specified /// \return A pointer to the updater; it will be NULL if the specified
/// zone isn't found. /// zone isn't found.
......
...@@ -438,6 +438,10 @@ public: ...@@ -438,6 +438,10 @@ public:
/// calls after \c commit() the implementation must throw a /// calls after \c commit() the implementation must throw a
/// \c DataSourceError exception. /// \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 /// \todo As noted above we may have to revisit the design details as we
/// gain experiences: /// gain experiences:
/// ///
...@@ -454,6 +458,8 @@ public: ...@@ -454,6 +458,8 @@ public:
/// ///
/// \exception DataSourceError Called after \c commit(), RRset is invalid /// \exception DataSourceError Called after \c commit(), RRset is invalid
/// (see above), internal data source error /// (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 /// \exception std::bad_alloc Resource allocation failure
/// ///
/// \param rrset The RRset to be added /// \param rrset The RRset to be added
...@@ -503,6 +509,10 @@ public: ...@@ -503,6 +509,10 @@ public:
/// calls after \c commit() the implementation must throw a /// calls after \c commit() the implementation must throw a
/// \c DataSourceError exception. /// \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 /// \todo As noted above we may have to revisit the design details as we
/// gain experiences: /// gain experiences:
/// ///
...@@ -520,6 +530,8 @@ public: ...@@ -520,6 +530,8 @@ public:
/// ///
/// \exception DataSourceError Called after \c commit(), RRset is invalid /// \exception DataSourceError Called after \c commit(), RRset is invalid
/// (see above), internal data source error /// (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 /// \exception std::bad_alloc Resource allocation failure
/// ///
/// \param rrset The RRset to be deleted /// \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