libdballe  7.19
Public Member Functions | Static Public Member Functions | List of all members
dballe::DB Class Referenceabstract
Inheritance diagram for dballe::DB:
dballe::db::v6::DB dballe::db::v7::DB

Public Member Functions

virtual db::Format format () const =0
 Return the format of this DB.
 
virtual void disappear ()=0
 Remove all our traces from the database, if applicable. More...
 
virtual void reset (const char *repinfo_file=0)=0
 Reset the database, removing all existing Db-All.e tables and re-creating them empty. More...
 
virtual void update_repinfo (const char *repinfo_file, int *added, int *deleted, int *updated)=0
 Update the repinfo table in the database, with the data found in the given file. More...
 
virtual std::map< std::string, int > get_repinfo_priorities ()=0
 Get a mapping between rep_memo and their priorities.
 
virtual std::unique_ptr< dballe::Transactiontransaction ()=0
 Begin a transaction on this database, and return a Transaction object that can be used to commit it.
 
void insert_station_data (StationValues &vals, bool can_replace, bool station_can_add)
 Insert station values into the database. More...
 
virtual void insert_station_data (dballe::Transaction &transaction, StationValues &vals, bool can_replace, bool station_can_add)=0
 Insert station values into the database. More...
 
void insert_data (DataValues &vals, bool can_replace, bool station_can_add)
 Insert data values into the database. More...
 
virtual void insert_data (dballe::Transaction &transaction, DataValues &vals, bool can_replace, bool station_can_add)=0
 Insert data values into the database. More...
 
void remove_station_data (const Query &query)
 Remove data from the database. More...
 
virtual void remove_station_data (dballe::Transaction &transaction, const Query &query)=0
 Remove data from the database. More...
 
void remove (const Query &query)
 Remove data from the database. More...
 
virtual void remove (dballe::Transaction &transaction, const Query &rec)=0
 Remove data from the database. More...
 
void remove_all ()
 Remove all data from the database. More...
 
virtual void remove_all (dballe::Transaction &transaction)=0
 Remove all data from the database. More...
 
virtual void vacuum ()=0
 Perform database cleanup operations. More...
 
virtual std::unique_ptr< db::CursorStationquery_stations (const Query &query)=0
 Start a query on the station variables archive. More...
 
virtual std::unique_ptr< db::CursorStationDataquery_station_data (const Query &query)=0
 Query the station variables in the database. More...
 
virtual std::unique_ptr< db::CursorDataquery_data (const Query &query)=0
 Query the database. More...
 
virtual std::unique_ptr< db::CursorSummaryquery_summary (const Query &query)=0
 Query a summary of what the result would be for a query. More...
 
virtual void attr_query_station (int data_id, std::function< void(std::unique_ptr< wreport::Var >)> &&dest)=0
 Query attributes on a station value. More...
 
virtual void attr_query_data (int data_id, std::function< void(std::unique_ptr< wreport::Var >)> &&dest)=0
 Query attributes on a data value. More...
 
void attr_insert_station (int data_id, const Values &attrs)
 Insert new attributes on a station value. More...
 
virtual void attr_insert_station (dballe::Transaction &transaction, int data_id, const Values &attrs)=0
 Insert new attributes on a station value. More...
 
void attr_insert_data (int data_id, const Values &attrs)
 Insert new attributes on a data value. More...
 
virtual void attr_insert_data (dballe::Transaction &transaction, int data_id, const Values &attrs)=0
 Insert new attributes on a data value. More...
 
void attr_remove_station (int data_id, const db::AttrList &attrs)
 Delete attributes from a station value. More...
 
virtual void attr_remove_station (dballe::Transaction &transaction, int data_id, const db::AttrList &attrs)=0
 Delete attributes from a station value. More...
 
void attr_remove_data (int data_id, const db::AttrList &attrs)
 Delete attributes from a data value. More...
 
virtual void attr_remove_data (dballe::Transaction &transaction, int data_id, const db::AttrList &attrs)=0
 Delete attributes from a data value. More...
 
virtual bool is_station_variable (int data_id, wreport::Varcode varcode)=0
 Check if this varcode and data_id correspond to a station variable. More...
 
void import_msg (const Message &msg, const char *repmemo, int flags)
 Import a Message into the DB-All.e database. More...
 
virtual void import_msg (dballe::Transaction &transaction, const Message &msg, const char *repmemo, int flags)=0
 Import a Message into the DB-All.e database. More...
 
void import_msgs (const Messages &msgs, const char *repmemo, int flags)
 Import Messages into the DB-All.e database. More...
 
virtual void import_msgs (dballe::Transaction &transaction, const Messages &msgs, const char *repmemo, int flags)
 Import Messages into the DB-All.e database. More...
 
bool export_msgs (const Query &query, std::function< bool(std::unique_ptr< Message > &&)> dest)
 Perform the query in `query', and send the results to dest. More...
 
virtual bool export_msgs (dballe::Transaction &transaction, const Query &query, std::function< bool(std::unique_ptr< Message > &&)> dest)=0
 Perform the query in `query', and send the results to dest. More...
 
virtual void dump (FILE *out)=0
 Dump the entire contents of the database to an output stream.
 
virtual void print_info (FILE *out)
 Print informations about the database to the given output stream.
 

Static Public Member Functions

static db::Format get_default_format ()
 
static void set_default_format (db::Format format)
 
static std::unique_ptr< DBconnect_from_file (const char *pathname)
 Create from a SQLite file pathname. More...
 
static std::unique_ptr< DBconnect_from_url (const char *url)
 Create from an url-like specification, as described in doc/fapi_connect.md. More...
 
static std::unique_ptr< DBconnect_memory (const std::string &arg=std::string())
 Create an in-memory database.
 
static std::unique_ptr< DBconnect_test ()
 Start a test session with DB-All.e. More...
 
static std::unique_ptr< DBcreate (std::unique_ptr< sql::Connection > conn)
 Create a database from an open Connection.
 
static bool is_url (const char *str)
 Return TRUE if the string looks like a DB URL. More...
 
static const char * default_repinfo_file ()
 Return the default repinfo file pathname.
 

Member Function Documentation

void dballe::DB::attr_insert_data ( int  data_id,
const Values attrs 
)

Insert new attributes on a data value.

Parameters
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
attrsThe attributes to be added
virtual void dballe::DB::attr_insert_data ( dballe::Transaction transaction,
int  data_id,
const Values attrs 
)
pure virtual

Insert new attributes on a data value.

Parameters
transactionThe current active transaction.
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
attrsThe attributes to be added

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::attr_insert_station ( int  data_id,
const Values attrs 
)

Insert new attributes on a station value.

Parameters
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
attrsThe attributes to be added
virtual void dballe::DB::attr_insert_station ( dballe::Transaction transaction,
int  data_id,
const Values attrs 
)
pure virtual

Insert new attributes on a station value.

Parameters
transactionThe current active transaction.
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
attrsThe attributes to be added

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual void dballe::DB::attr_query_data ( int  data_id,
std::function< void(std::unique_ptr< wreport::Var >)> &&  dest 
)
pure virtual

Query attributes on a data value.

Parameters
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
destThe function that will be called on each resulting attribute

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual void dballe::DB::attr_query_station ( int  data_id,
std::function< void(std::unique_ptr< wreport::Var >)> &&  dest 
)
pure virtual

Query attributes on a station value.

Parameters
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
destThe function that will be called on each resulting attribute

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::attr_remove_data ( int  data_id,
const db::AttrList &  attrs 
)

Delete attributes from a data value.

Parameters
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
attrsArray of WMO codes of the attributes to delete. If empty, all attributes associated to the value will be deleted.
virtual void dballe::DB::attr_remove_data ( dballe::Transaction transaction,
int  data_id,
const db::AttrList &  attrs 
)
pure virtual

Delete attributes from a data value.

Parameters
transactionThe current active transaction.
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
attrsArray of WMO codes of the attributes to delete. If empty, all attributes associated to the value will be deleted.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::attr_remove_station ( int  data_id,
const db::AttrList &  attrs 
)

Delete attributes from a station value.

Parameters
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
attrsArray of WMO codes of the attributes to delete. If empty, all attributes associated to the value will be deleted.
virtual void dballe::DB::attr_remove_station ( dballe::Transaction transaction,
int  data_id,
const db::AttrList &  attrs 
)
pure virtual

Delete attributes from a station value.

Parameters
transactionThe current active transaction.
data_idThe id (returned by Cursor::attr_reference_id()) used to refer to the value
attrsArray of WMO codes of the attributes to delete. If empty, all attributes associated to the value will be deleted.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

static std::unique_ptr<DB> dballe::DB::connect_from_file ( const char *  pathname)
static

Create from a SQLite file pathname.

Parameters
pathnameThe pathname to a SQLite file
static std::unique_ptr<DB> dballe::DB::connect_from_url ( const char *  url)
static

Create from an url-like specification, as described in doc/fapi_connect.md.

Parameters
urlThe url-like connection descriptor
static std::unique_ptr<DB> dballe::DB::connect_test ( )
static

Start a test session with DB-All.e.

Take information from the environment (

See also
dba_db_create_from_env) and default to ./test.sqlite if nothing is specified.

Referenced by dballe::benchmark::DBTask::setup().

virtual void dballe::DB::disappear ( )
pure virtual

Remove all our traces from the database, if applicable.

After this has been called, all other DB methods except for reset() will fail.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

bool dballe::DB::export_msgs ( const Query query,
std::function< bool(std::unique_ptr< Message > &&)>  dest 
)

Perform the query in `query', and send the results to dest.

Return false from dest to interrupt the query.

Parameters
queryThe query to perform
destThe function that will handle the resulting messages
Returns
true if the query reached its end, false if it got interrupted because dest returned false.
virtual bool dballe::DB::export_msgs ( dballe::Transaction transaction,
const Query query,
std::function< bool(std::unique_ptr< Message > &&)>  dest 
)
pure virtual

Perform the query in `query', and send the results to dest.

Return false from dest to interrupt the query.

Parameters
transactionThe current active transaction.
queryThe query to perform
destThe function that will handle the resulting messages
Returns
true if the query reached its end, false if it got interrupted because dest returned false.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::import_msg ( const Message msg,
const char *  repmemo,
int  flags 
)

Import a Message into the DB-All.e database.

Parameters
msgThe Message containing the data to import
repmemoReport mnemonic to which imported data belong. If NULL is passed, then it will be chosen automatically based on the message type.
flagsCustomise different aspects of the import process. It is a bitmask of the various DBA_IMPORT_* macros.
virtual void dballe::DB::import_msg ( dballe::Transaction transaction,
const Message msg,
const char *  repmemo,
int  flags 
)
pure virtual

Import a Message into the DB-All.e database.

Parameters
transactionThe current active transaction.
msgThe Message containing the data to import
repmemoReport mnemonic to which imported data belong. If NULL is passed, then it will be chosen automatically based on the message type.
flagsCustomise different aspects of the import process. It is a bitmask of the various DBA_IMPORT_* macros.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::import_msgs ( const Messages msgs,
const char *  repmemo,
int  flags 
)

Import Messages into the DB-All.e database.

Parameters
msgsThe Messages containing the data to import
repmemoReport mnemonic to which imported data belong. If NULL is passed, then it will be chosen automatically based on the message type.
flagsCustomise different aspects of the import process. It is a bitmask of the various DBA_IMPORT_* macros.
virtual void dballe::DB::import_msgs ( dballe::Transaction transaction,
const Messages msgs,
const char *  repmemo,
int  flags 
)
virtual

Import Messages into the DB-All.e database.

Parameters
transactionThe current active transaction.
msgsThe Messages containing the data to import
repmemoReport mnemonic to which imported data belong. If NULL is passed, then it will be chosen automatically based on the message type.
flagsCustomise different aspects of the import process. It is a bitmask of the various DBA_IMPORT_* macros.
void dballe::DB::insert_data ( DataValues vals,
bool  can_replace,
bool  station_can_add 
)

Insert data values into the database.

The IDs of the station andl all variables that were inserted will be stored in vals.

Parameters
valsThe values to insert.
can_replaceIf true, then existing data can be rewritten, else data can only be added.
station_can_addIf false, it will not create a missing station record, and only data for existing stations can be added. If true, then if we are inserting data for a station that does not yet exists in the database, it will be created.
virtual void dballe::DB::insert_data ( dballe::Transaction transaction,
DataValues vals,
bool  can_replace,
bool  station_can_add 
)
pure virtual

Insert data values into the database.

The IDs of the station andl all variables that were inserted will be stored in vals.

Parameters
transactionThe current active transaction.
valsThe values to insert.
can_replaceIf true, then existing data can be rewritten, else data can only be added.
station_can_addIf false, it will not create a missing station record, and only data for existing stations can be added. If true, then if we are inserting data for a station that does not yet exists in the database, it will be created.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::insert_station_data ( StationValues vals,
bool  can_replace,
bool  station_can_add 
)

Insert station values into the database.

The IDs of the station andl all variables that were inserted will be stored in vals.

Parameters
valsThe values to insert.
can_replaceIf true, then existing data can be rewritten, else data can only be added.
station_can_addIf false, it will not create a missing station record, and only data for existing stations can be added. If true, then if we are inserting data for a station that does not yet exists in the database, it will be created.
virtual void dballe::DB::insert_station_data ( dballe::Transaction transaction,
StationValues vals,
bool  can_replace,
bool  station_can_add 
)
pure virtual

Insert station values into the database.

The IDs of the station andl all variables that were inserted will be stored in vals.

Parameters
transactionThe current active transaction.
valsThe values to insert.
can_replaceIf true, then existing data can be rewritten, else data can only be added.
station_can_addIf false, it will not create a missing station record, and only data for existing stations can be added. If true, then if we are inserting data for a station that does not yet exists in the database, it will be created.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual bool dballe::DB::is_station_variable ( int  data_id,
wreport::Varcode  varcode 
)
pure virtual

Check if this varcode and data_id correspond to a station variable.

This is used only to implement attr_* functions to be used when this information is not known. A database for which this information is not relevant (for example, in v6 databases there is a single ID space for station and data variable) can return any arbitrary value, since later they will be ignored.

This should disappear once client APIs start making a distinction between attributes in station variables and attributes on data variables.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

static bool dballe::DB::is_url ( const char *  str)
static

Return TRUE if the string looks like a DB URL.

Parameters
strThe string to test
Returns
true if it looks like a URL, else false
virtual std::unique_ptr<db::CursorData> dballe::DB::query_data ( const Query query)
pure virtual

Query the database.

When multiple values per variable are present, the results will be presented in increasing order of priority.

Parameters
queryThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input")
Returns
The cursor to use to iterate over the results

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual std::unique_ptr<db::CursorStationData> dballe::DB::query_station_data ( const Query query)
pure virtual

Query the station variables in the database.

When multiple values per variable are present, the results will be presented in increasing order of priority.

Parameters
queryThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input")
Returns
The cursor to use to iterate over the results

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual std::unique_ptr<db::CursorStation> dballe::DB::query_stations ( const Query query)
pure virtual

Start a query on the station variables archive.

The cursor will iterate over unique lat, lon, ident triples, and will contain all station vars. If a station var exists twice on two different networks, only one will be present: the one of the network with the highest priority.

Parameters
queryThe record with the query data (see Keywords used by dballe::Record)
Returns
The cursor to use to iterate over the results

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual std::unique_ptr<db::CursorSummary> dballe::DB::query_summary ( const Query query)
pure virtual

Query a summary of what the result would be for a query.

Parameters
queryThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input")
Returns
The cursor to use to iterate over the results. The results are the same as query_data, except that no context_id, datetime and value are provided, so it only gives all the available combinations of data contexts.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::remove ( const Query query)

Remove data from the database.

Parameters
recThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input") to select the items to be deleted
virtual void dballe::DB::remove ( dballe::Transaction transaction,
const Query rec 
)
pure virtual

Remove data from the database.

Parameters
transactionThe current active transaction.
recThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input") to select the items to be deleted

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::remove_all ( )

Remove all data from the database.

This is faster than remove() with an empty record, and unlike reset() it preserves existing report information.

virtual void dballe::DB::remove_all ( dballe::Transaction transaction)
pure virtual

Remove all data from the database.

This is faster than remove() with an empty record, and unlike reset() it preserves existing report information.

Parameters
transactionThe current active transaction.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

void dballe::DB::remove_station_data ( const Query query)

Remove data from the database.

Parameters
queryThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input") to select the items to be deleted
virtual void dballe::DB::remove_station_data ( dballe::Transaction transaction,
const Query query 
)
pure virtual

Remove data from the database.

Parameters
transactionThe current active transaction.
queryThe record with the query data (see technical specifications, par. 1.6.4 "parameter output/input") to select the items to be deleted

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual void dballe::DB::reset ( const char *  repinfo_file = 0)
pure virtual

Reset the database, removing all existing Db-All.e tables and re-creating them empty.

Parameters
repinfo_fileThe name of the CSV file with the report type information data to load. The file is in CSV format with 6 columns: report code, mnemonic id, description, priority, descriptor, table A category. If repinfo_file is NULL, then the default of /etc/dballe/repinfo.csv is used.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual void dballe::DB::update_repinfo ( const char *  repinfo_file,
int *  added,
int *  deleted,
int *  updated 
)
pure virtual

Update the repinfo table in the database, with the data found in the given file.

Parameters
repinfo_fileThe name of the CSV file with the report type information data to load. The file is in CSV format with 6 columns: report code, mnemonic id, description, priority, descriptor, table A category. If repinfo_file is NULL, then the default of /etc/dballe/repinfo.csv is used.
Return values
addedThe number of repinfo entries that have been added
deletedThe number of repinfo entries that have been deleted
updatedThe number of repinfo entries that have been updated

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.

virtual void dballe::DB::vacuum ( )
pure virtual

Perform database cleanup operations.

Orphan values are currently:

  • context values for which no data exists
  • station values for which no context exists

Depending on database size, this routine can take a few minutes to execute.

Implemented in dballe::db::v6::DB, and dballe::db::v7::DB.


The documentation for this class was generated from the following file: