diff --git a/src/fdb5/api/FDB.h b/src/fdb5/api/FDB.h index 28529795c..d763d5aaf 100644 --- a/src/fdb5/api/FDB.h +++ b/src/fdb5/api/FDB.h @@ -71,72 +71,253 @@ 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 - /// @note always safe to call + /** 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); + /** + * @TODO: Comment me pls. + * + * \param request a mars request which should be inspected + * + * \return ListIterator + */ 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