|
@@ -1,83 +1,116 @@
|
|
|
namespace {
|
|
|
const char* const ZoneLoader_doc = "\
|
|
|
-\n\
|
|
|
Class to load data into a data source client.\n\
|
|
|
\n\
|
|
|
-This is a small wrapper class that is able to load data into a data source.\n\
|
|
|
-It can load either from another data source or from a master file. The\n\
|
|
|
-purpose of the class is only to hold the state for incremental loading.\n\
|
|
|
+This is a small wrapper class that is able to load data into a data\n\
|
|
|
+source. It can load either from another data source or from a master\n\
|
|
|
+file. The purpose of the class is only to hold the state for\n\
|
|
|
+incremental loading.\n\
|
|
|
\n\
|
|
|
The old content of zone is discarded and no journal is stored.\n\
|
|
|
\n\
|
|
|
-The constructor takes three arguments:\n\
|
|
|
-- The datasource (isc.datasrc.DataSourceClient) to load the zone into\n\
|
|
|
-- The name (isc.dns.Name) to load\n\
|
|
|
-- either a string (for a file) or another DataSourceClient to load from\n\
|
|
|
-\n\
|
|
|
-Upon construction, no loading is done yet.\n\
|
|
|
-\n\
|
|
|
-It can throw:\n\
|
|
|
-DataSourceError, in case the zone does not exist in destination.\n\
|
|
|
- This class does not support creating brand new zones, only loading\n\
|
|
|
- data into them. In case a new zone is needed, it must be created\n\
|
|
|
- beforehand (with create_zone()).\n\
|
|
|
- DataSourceError is also thrown in case the zone is not present in the\n\
|
|
|
- source DataSourceClient, and in case of other possibly low-level\n\
|
|
|
- errors.\n\
|
|
|
-InvalidParameter, in case the class of destination and source\n\
|
|
|
- differs.\n\
|
|
|
-NotImplemented in case target data source client doesn't provide an updater\n\
|
|
|
- or the source data source client doesn't provide an iterator.\n\
|
|
|
+ZoneLoader(destination, zone_name, master_file)\n\
|
|
|
+\n\
|
|
|
+ Constructor from master file.\n\
|
|
|
+\n\
|
|
|
+ This initializes the zone loader to load from a master file.\n\
|
|
|
+\n\
|
|
|
+ Exceptions:\n\
|
|
|
+ DataSourceError in case the zone does not exist in destination.\n\
|
|
|
+ This class does not support creating brand new zones,\n\
|
|
|
+ only loading data into them. In case a new zone is\n\
|
|
|
+ needed, it must be created beforehand.\n\
|
|
|
+ DataSourceError in case of other (possibly low-level) errors,\n\
|
|
|
+ such as read-only data source or database error.\n\
|
|
|
+\n\
|
|
|
+ Parameters:\n\
|
|
|
+ destination (isc.datasrc.DataSourceClient) The data source into\n\
|
|
|
+ which the loaded data should go.\n\
|
|
|
+ zone_name (isc.dns.Name) The origin of the zone. The class is\n\
|
|
|
+ implicit in the destination.\n\
|
|
|
+ master_file (string) Path to the master file to read data from.\n\
|
|
|
+\n\
|
|
|
+ZoneLoader(destination, zone_name, source)\n\
|
|
|
+\n\
|
|
|
+ Constructor from another data source.\n\
|
|
|
+\n\
|
|
|
+ Parameters:\n\
|
|
|
+ destination (isc.datasrc.DataSourceClient) The data source into\n\
|
|
|
+ which the loaded data should go.\n\
|
|
|
+ zone_name (isc.dns.Name) The origin of the zone. The class is\n\
|
|
|
+ implicit in the destination.\n\
|
|
|
+ source (isc.datasrc.DataSourceClient) The data source from\n\
|
|
|
+ which the data would be read.\n\
|
|
|
+\n\
|
|
|
+ Exceptions:\n\
|
|
|
+ InvalidParameter in case the class of destination and source\n\
|
|
|
+ differs.\n\
|
|
|
+ NotImplemented in case the source data source client doesn't\n\
|
|
|
+ provide an iterator.\n\
|
|
|
+ DataSourceError in case the zone does not exist in destination.\n\
|
|
|
+ This class does not support creating brand new zones,\n\
|
|
|
+ only loading data into them. In case a new zone is\n\
|
|
|
+ needed, it must be created beforehand.\n\
|
|
|
+ DataSourceError in case the zone does not exist in the source.\n\
|
|
|
+ DataSourceError in case of other (possibly low-level) errors,\n\
|
|
|
+ such as read-only data source or database error.\n\
|
|
|
+\n\
|
|
|
+ Parameters:\n\
|
|
|
+ destination The data source into which the loaded data should\n\
|
|
|
+ go.\n\
|
|
|
+ zone_name The origin of the zone.\n\
|
|
|
+ source The data source from which the data would be read.\n\
|
|
|
\n\
|
|
|
";
|
|
|
|
|
|
-const char* const ZoneLoader_loadIncremental_doc = "\
|
|
|
-\n\
|
|
|
-Load up to limit RRs.\n\
|
|
|
-\n\
|
|
|
-This performs a part of the loading. In case there's enough data in the\n\
|
|
|
-source, it copies limit RRs. It can copy less RRs during the final call\n\
|
|
|
-(when there's less than limit left).\n\
|
|
|
-\n\
|
|
|
-This can be called repeatedly until the whole zone is loaded, having\n\
|
|
|
-pauses in the loading for some purposes (for example reporting\n\
|
|
|
-progress).\n\
|
|
|
-\n\
|
|
|
-It has one parameter: limit (integer), The maximum allowed number of RRs\n\
|
|
|
-to be loaded during this call.\n\
|
|
|
+const char* const ZoneLoader_load_doc = "\
|
|
|
+load() -> None\n\
|
|
|
\n\
|
|
|
-Returns True in case the loading is completed, and False if there's more\n\
|
|
|
-to load.\n\
|
|
|
+Perform the whole load.\n\
|
|
|
\n\
|
|
|
-It can throw:\n\
|
|
|
-InvalidOperation, in case the loading was already completed before this\n\
|
|
|
- call (by load() or by a loadIncremental that returned true).\n\
|
|
|
-DataSourceError, in case some error (possibly low-level) happens.\n\
|
|
|
-MasterFileError when the master_file is badly formatted or some similar\n\
|
|
|
- problem is found when loading the master file.\n\
|
|
|
+This performs the whole loading operation. It may take a long time.\n\
|
|
|
\n\
|
|
|
-Note: If the limit is exactly the number of RRs available to be loaded,\n\
|
|
|
- the method still returns false and true'll be returned on the next\n\
|
|
|
- call (which will load 0 RRs). This is because the end of iterator or\n\
|
|
|
- master file is detected when reading past the end, not when the last\n\
|
|
|
- one is read.\n\
|
|
|
+Exceptions:\n\
|
|
|
+ InvalidOperation in case the loading was already completed before\n\
|
|
|
+ this call.\n\
|
|
|
+ DataSourceError in case some error (possibly low-level) happens.\n\
|
|
|
+ MasterFileError when the master_file is badly formatted or some\n\
|
|
|
+ similar problem is found when loading the master file.\n\
|
|
|
\n\
|
|
|
";
|
|
|
|
|
|
-const char* const ZoneLoader_load_doc = "\
|
|
|
-\n\
|
|
|
-Performs the entire load operation.\n\
|
|
|
+const char* const ZoneLoader_loadIncremental_doc = "\
|
|
|
+load_incremental(limit) -> bool\n\
|
|
|
\n\
|
|
|
-Depending on zone size, this could take a long time.\n\
|
|
|
+Load up to limit RRs.\n\
|
|
|
\n\
|
|
|
-This method has no parameters and does not return anything.\n\
|
|
|
+This performs a part of the loading. In case there's enough data in\n\
|
|
|
+the source, it copies limit RRs. It can copy less RRs during the final\n\
|
|
|
+call (when there's less than limit left).\n\
|
|
|
\n\
|
|
|
-It can throw:\n\
|
|
|
-InvalidOperation, in case the loading was already completed before this call.\n\
|
|
|
-MasterFileError, when the master_file is badly formatted or some\n\
|
|
|
- similar problem is found when loading the master file.\n\
|
|
|
-DataSourceError, in case some error (possibly low-level) happens.\n\
|
|
|
+This can be called repeatedly until the whole zone is loaded, having\n\
|
|
|
+pauses in the loading for some purposes (for example reporting\n\
|
|
|
+progress).\n\
|
|
|
\n\
|
|
|
+Exceptions:\n\
|
|
|
+ InvalidOperation in case the loading was already completed before\n\
|
|
|
+ this call (by load() or by a load_incremental that\n\
|
|
|
+ returned true).\n\
|
|
|
+ DataSourceError in case some error (possibly low-level) happens.\n\
|
|
|
+ MasterFileError when the master_file is badly formatted or some\n\
|
|
|
+ similar problem is found when loading the master file.\n\
|
|
|
+\n\
|
|
|
+Parameters:\n\
|
|
|
+ limit (integer) The maximum allowed number of RRs to be\n\
|
|
|
+ loaded during this call.\n\
|
|
|
+\n\
|
|
|
+Return Value(s): True in case the loading is completed, false if\n\
|
|
|
+there's more to load.\n\
|
|
|
+\n\
|
|
|
+Note that if the limit is exactly the number of RRs available to be\n\
|
|
|
+loaded, the method will still return False, and True will be returned\n\
|
|
|
+on the next call (which will load 0 RRs). This is because the end of\n\
|
|
|
+iterator or master file is detected when reading past the end, not\n\
|
|
|
+when the last one is read.\n\
|
|
|
";
|
|
|
-
|
|
|
} // unnamed namespace
|