diff --git a/src/fdb5/api/FDB.h b/src/fdb5/api/FDB.h index 28529795c..7cecda975 100644 --- a/src/fdb5/api/FDB.h +++ b/src/fdb5/api/FDB.h @@ -71,72 +71,179 @@ class FDB { // -------------- Primary API functions ---------------------------- + /// Archive binary data to a FDB. + /// @param handle eckit::message::Message to data to archive void archive(eckit::message::Message msg); + + /// Archive binary data to a FDB. + /// Reads messages from the eckit::DataHandle and calls archive() the the + /// corresponding messages. + /// @param handle eckit::DataHandle reference data to archive void archive(eckit::DataHandle& handle); + + /// Archive binary data to a FDB. + /// Internally creates a DataHandle and calls archive(). + /// @param data Pointer to the binary data to archive + /// @param length Size of the data to archive with the given void archive(const void* data, size_t length); - // warning: not high-perf API - makes sure that all the requested fields are archived and there are no data exceeding the request + + /// Archive binary data of a mars request and the corresponding binary data to a FDB. + /// @warning not high-perf API - makes sure that all the requested fields are archived + /// and there are no data exceeding the request + /// @param request a mars request + /// @param handle a data handle pointing to the data void archive(const metkit::mars::MarsRequest& request, eckit::DataHandle& handle); - // disclaimer: this is a low-level API. The provided key and the corresponding data are not checked for consistency - // Optional callback function is called upon receiving field location from the store. + /// Archive binary data to a FDB. + /// @warning this is a low-level API. The provided key and the corresponding + /// data are not checked for consistency. Optional callback function is called upon + /// receiving field location from the store. + /// @param key Key used for indexing and archiving the data + /// @param data Pointer to the binary data to archive + /// @param length Size of the data to archive with the given @p key void archive(const Key& key, const void* data, size_t length); - /// Flushes all buffers and closes all data handles into a consistent DB state + /// Flush all buffers and closes all data handles into a consistent DB state /// @note always safe to call void flush(); + /// Read binary data from an URI. + /// @param uri eckit uri to the data source + /// @return DataHandle for reading the requested data from eckit::DataHandle* read(const eckit::URI& uri); + /// Read binary data from an list of URI. + /// @param vector of uris eckit uris to the data source + /// @param sorted bool whether the given uris should be sorted + /// @return DataHandle for reading the requested data from eckit::DataHandle* read(const std::vector& uris, bool sorted = false); + /// Read binary from a ListIterator. + /// @param uris a list iterator which resembles a set of fields which should be read + /// @param sorted bool whether the given uris should be sorted + /// @return DataHandle for reading the requested data from eckit::DataHandle* read(ListIterator& it, bool sorted = false); + /// Retrieve data which is specified by a MARS request. + /// @param request MarsRequest which describes the data which should be retrieved + /// @return DataHandle for reading the requested data from eckit::DataHandle* retrieve(const metkit::mars::MarsRequest& request); ListIterator inspect(const metkit::mars::MarsRequest& request); + /// List data present at the archive and which can be retrieved. + /// @param request FDBToolRequest stating which data should be queried + /// @param deduplicate bool whether the returned iterator should ignore duplicates + /// @param length Size of the data to archive with the given @p key + /// @return ListIterator for iterating over the set of found items ListIterator list(const FDBToolRequest& request, bool deduplicate=false); + /// Dump the structural content of the FDB + /// In particular, in the TOC formulation, enumerate the different entries + /// in the Table of Contents (including INIT and CLEAR entries). + /// The dump will include information identifying the data files that are + /// referenced, and the "Axes" which describe the maximum possible extent of + /// the data that is contained in the database. + /// @return DumpIterator for iterating over the set of found items DumpIterator dump(const FDBToolRequest& request, bool simple=false); - /// TODO: Is this function superfluous given the control() function? StatusIterator status(const FDBToolRequest& request); + /// Wipe data from the database. + /// Deletes FDB databases and the data therein contained. Uses the passed + /// request to identify the database to delete. This is equivalent to a + /// UNIX rm command. + /// This tool deletes either whole databases, or whole indexes within databases + /// @param request FDBToolRequest stating which data should be queried + /// @param doit flag for committing to the wipe (default is dry-run) + /// @param porcelain flag print only a list of files to be deleted / that are deleted + /// @param unsafeWipeAll flag for omitting all security checks and force a wipe + /// @return WipeIterator for iterating over the set of wiped items WipeIterator wipe(const FDBToolRequest& request, bool doit=false, bool porcelain=false, bool unsafeWipeAll=false); + /// Move content of one FDB database. + /// This locks the source database, make it possible to create a second + /// database in another root, duplicates all data. Source data are not automatically removed. + /// @param request a fdb tool request for the data which should be move + /// @param dest destination uri to which the data should be moved + /// @return MoveIterator for iterating over the set of found items MoveIterator move(const FDBToolRequest& request, const eckit::URI& dest); + /// Remove duplicate data from the database. + /// Purge duplicate entries from the database and remove the associated data + /// (if the data is owned, not adopted). + /// Data in the FDB5 is immutable. It is masked, but not damaged or deleted, + /// when it is overwritten with new data using the same key. + /// If an index or data file only contains masked data + /// (i.e. no data that can be obtained using normal requests), + /// then those indexes and data files may be removed. + /// If an index refers to data that is not owned by the FDB + /// (in particular data which has been adopted from an existing FDB4), + /// this data will not be removed. + /// @param request a fdb tool request for the data which should be purged + /// @param doit bool if true the purge is triggered, otherwise a dry-run is executed + /// @param porcelain bool for printing only those files which are deleted + /// @return PurgeIterator for iterating over the set of found items PurgeIterator purge(const FDBToolRequest& request, bool doit=false, bool porcelain=false); + /// Prints information about FDB databases, aggregating the + /// information over all the databases visited into a final summary. + /// @param request FDB tool request for which the stats should be shown + /// @return StatsIterator for iterating over the set of found items StatsIterator stats(const FDBToolRequest& request); + /// @todo Comment me pls + /// @param request FDB tool request + /// @param action control action + /// @param identifiers identifiers + /// @return ControlIterator for iterating over the set of found items ControlIterator control(const FDBToolRequest& request, ControlAction action, ControlIdentifiers identifiers); + /// @todo Comment me pls + /// @param request FDB tool request + /// @param level maximum level the axis visitor should respect + /// @return IndexAxis IndexAxis axes(const FDBToolRequest& request, int level=3); + /// @todo Comment me pls + /// @param request FDB tool request + /// @param level maximum level the axis visitor should respect + /// @return AxisIterator AxesIterator axesIterator(const FDBToolRequest& request, int level=3); + /// Check whether a specific control identifier is enabled + /// @param controlIdentifier a given control identifier + /// @return bool true or false, depending on the internal status of the FDB bool enabled(const ControlIdentifier& controlIdentifier) const; + /// Return whether a flush of the FDB is needed + /// @return true if an archive has happened and a flush is needed bool dirty() const; + /// Register an archive callback. + /// @param callback an archive callback which should be triggered during archive void registerArchiveCallback(ArchiveCallback callback); + + /// Register a flush callback. + /// @param callback an flush callback which should be triggered during flushing void registerFlushCallback(FlushCallback callback); // -------------- API management ---------------------------- - /// ID used for hashing in the Rendezvous hash. Should be unique. const std::string id() const; FDBStats stats() const; + FDBStats internalStats() const; const std::string& name() const; + const Config& config() const; void disable(); + bool disabled() const; private: // methods