Key classes in namespace tom::tsdb

class engine

engine is the singleton class that controls all access to tsdb assets including sessions, connections, datastores, time_series, and more. It also handles the runtime requirements of locating and loading the various modules that provide persistence handling.

Public Functions

~engine()

provider &get_provider(): Retrieve the provider for the default session as defined in the tom-environment.xml config file.

inline provider &get_provider(const char *name): Retrieve the provider for the repository with name = ‘name’ as defined in the tom-environment.xml config file.

provider &get_provider(const tom::observation &name): Retrieve the provider for the repository with name = ‘name’ as defined in the tom-environment.xml config file.

const repository_meta_data_vec &get_repositories_meta_data() const: Retrieve a vector of repository_meta_data that describes the repositories available on this system as described in the tom-environment.xml config file.

session_sptr get_session(): Retrieve the default session object as defined in the tom-environment.xml config file.

inline session_sptr get_session(const char *name): Retrieve a session for the repository with name = ‘name’

session_sptr get_session(const tom::observation &name): Retrieve a session for the repository with name = ‘name’

void update_screening_dbs()

Public Static Functions

static engine &Instance(): engine is a singleton, and may only be accessed via the static Instance() method. The first time the Instance method is called, it may throw exceptions concerning a malformed tom-environment.xml config file, or possibly directory rights when reading the specified module directory. Subsequent calls need not worry about exceptions

static inline bool use_screening_dbs()

static inline void use_screening_dbs(bool use)

static const char *version(): Get the version for the tsdb library.

class module_loader : public tom::module_loader

Public Functions

module_loader(const tom::String dir)

virtual ~module_loader()

provider &get_provider(const tom::observation &name)

class session

sessions are the top level objects that control all interaction with a given repository. Repositories are logical groupings of data that use one persistence back-end. For example, you may have US Equity Data stored in a FAME database within a repository that contained US Market Data, and Compustat Data in an ORACLE server within a repository of US Fundamentals data.

Repositories are configured in the tom-environment.xml file. See the documentation for tsdb configuration for more details.

Public Functions

inline virtual ~session()

inline void extended_functions(const char *cmd, const char *args): many persistence backends may offer extended functions that can be called throught this session method. See back-end documentation for more information

inline void extended_functions(const char *cmd, const observation &args): many persistence backends may offer extended functions that can be called throught this session method. See back-end documentation for more information

inline void extended_functions(const observation &cmd, const char *args): many persistence backends may offer extended functions that can be called throught this session method. See back-end documentation for more information

virtual void extended_functions(const observation &cmd, const observation &args): many persistence backends may offer extended functions that can be called throught this session method. See back-end documentation for more information

virtual connection_sptr get_connection() = 0: get the default connection object for this session. This typically will be to local file-systems, or a local server

virtual connection_sptr get_connection(const connection_info&) = 0: get a connection for a remote or local service as specified by the connection_info object

virtual const connection_meta_data_vec &get_connections_meta_data() const = 0: get a vector of connection meta data for connections defined for this repository

virtual const provider &get_provider() const = 0: get the provider used to manage the persistence for this session, e.g., FAME, BDB, ORACLE, MySQL, etc…

virtual const tom::String &name() const = 0: get the name of the session

class connection

connection objects control all access to time-series datastores. The normal create/access/delete and information methods as well

Public Functions

inline virtual ~connection()

void delete_datastore(const char *name): delete a datastore with the path specified by name

virtual void delete_datastore(const observation &name) = 0: delete a datastore with the path specified by name

tom::tsdb::datastore_sptr get_datastore(const char *name, const access_mode &mode): get a datastore with the path specified by name, using the appropriate access_mode. This can create datastores as well via the access_mode::create() mode.

virtual tom::tsdb::datastore_sptr get_datastore(const observation &name, const access_mode &mode) = 0: get a datastore with the path specified by name, using the appropriate access_mode. This can create datastores as well via the access_mode::create() mode.

virtual const datastore_meta_data_vec &get_datastores_meta_data() const = 0: get a vector of datastore_meta_data for all datastores available for the given connection object

inline const lock_metrics &get_lock_metrics()

virtual tom::tsdb::session &get_session() = 0: get the connection’s parent session object.

class datastore : public tom::tsdb::logger

Datastore objects are the meat and potatoes of time-series creation, retrieval, updating, and deletion. All time-series start there life out deep in the bowels of some datastore. Whether creating one for the first time, or retrieving previously created ones, it is easiest to use the datastore object.

Public Functions

inline datastore(const access_mode &mode)

inline virtual ~datastore()

virtual void close() = 0: All datastore objects MUST be closed at the end of a session. It is the only resource that has any requirement at all. All other objects fall under the perview of the garbage collection framework, and have no such clean-up requirements

tom::tsdb::sparse_series_sptr create_sparse_series(const char *name, native_data_type data_t, native_calendar_type calendar_t, aggregation_type): create a sparse_series object with the name=’name’, the native_data_type, native_calendar_type, and aggregation_type. Users can directly invoke constructors for the underlying template classes but this can be considerably more ugly in code, so these helpers are provided. The resulting sparse_series objects have the current datastore object as its parent but do not actually get creating in the datastore until the save method of the sparse_series or the datastore is called on it.

virtual tom::tsdb::sparse_series_sptr create_sparse_series(const tom::observation &name, native_data_type data_t, native_calendar_type calendar_t, aggregation_type): create a sparse_series object with the name=’name’, the native_data_type, native_calendar_type, and aggregation_type. Users can directly invoke constructors for the underlying template classes but this can be considerably more ugly in code, so these helpers are provided. The resulting sparse_series objects have the current datastore object as its parent but do not actually get creating in the datastore until the save method of the sparse_series or the datastore is called on it.

tom::tsdb::time_series_sptr create_time_series(const char *name, native_data_type data_t, native_calendar_type calendar_t, aggregation_type): create a time_series object with the name=’name’, the native_data_type, native_calendar_type, and aggregation_type. Users can directly invoke constructors for the underlying template classes but this can be considerably more ugly in code, so these helpers are provided. The resulting time_series objects have the current datastore object as its parent but do not actually get created in the datastore until the save method of the time_series or the datastore is called on it.

virtual tom::tsdb::time_series_sptr create_time_series(const tom::observation &name, native_data_type data_t, native_calendar_type calendar_t, aggregation_type): create a time_series object with the name=’name’, the native_data_type, native_calendar_type, and aggregation_type. Users can directly invoke constructors for the underlying template classes but this can be considerably more ugly in code, so these helpers are provided. The resulting time_series objects have the current datastore object as its parent but do not actually get creating in the datastore until the save method of the time_series or the datastore is called on it.

bool delete_time_series(const char *name): delete the time_series with name=’name’. This method may also throw derivatives of std::runtime_error if internal failures occur, and should be hence wrapped in a try block.

virtual bool delete_time_series(const tom::observation &name) = 0: delete the time_series with name=’name’. This method may also throw derivatives of std::runtime_error if internal failures occur, and should be hence wrapped in a try block.

virtual tom::tsdb::connection &get_connection() = 0: get the parent connection that created this datastore object

virtual const tom::calendars::date_time &get_create_date_time() const = 0: get the create date_time stamp of the datastore object

inline const datastore_metrics &get_datastore_metrics()

virtual const tom::string &get_description() const = 0: get the description of the datastore object

virtual const tom::string &get_documentation() const = 0: get the documentation of the datastore object

inline const access_mode &get_mode() const: get the access_mode used to open this datastore

virtual const tom::calendars::date_time &get_modify_date_time() const = 0: get the modify date_time stamp of the datastore object

virtual const tom::string &get_name() const = 0: get the name of the datastore object

tom::tsdb::time_series_sptr get_time_series(const char *name, bool lazy_eval = false): get a time_series object with name = ‘name’ set lazy_eval to true will inform the back-end that no data need be read other than the time-series meta-data. This is useful for performance reasons when updating time-series during loads, etc. and the default is the normal course of use and may be left out. This method will throw a dervivative of std::runtime_error if the object does not exist and should be caught.

virtual tom::tsdb::time_series_sptr get_time_series(const tom::observation &name, bool lazy_eval = false) = 0: get a time_series object with name = ‘name’ set lazy_eval to true will inform the back-end that no data need be read other than the time-series meta-data. This is useful for performance reasons when updating time-series during loads, etc. and the default is the normal course of use and may be left out. This method will throw a dervivative of std::runtime_error if the object does not exist and should be caught.

inline bool has_time_series(const char *name): Check if the time_series with the name=’name’ exists in the datastore. This is useful for example if bulk data operations are underway that may result in large number of time_series being created. This method avoids the overhead of the exception framework and has been found to save considerable time in loads and other large scale time_series creation.

virtual bool has_time_series(const tom::observation &name) = 0: Check if the time_series with the name=’name’ exists in the datastore. This is useful for example if bulk data operations are underway that may result in large number of time_series being created. This method avoids the overhead of the exception framework and has been found to save considerable time in loads and other large scale time_series creation.

virtual bool is_open() const = 0: check if the datastore has already been closed

tom::tsdb::datastore_match_sptr regex_name_search(const char *regex): datastore objects provide full extended posix regex search capabilities on the datastore. This allows for rich querying of the datastore based on time_series names which typically follow semantics to create naturally grouped objects, e.g., regex_name_search( “IBM..*” ); would return all objects starting with ‘IBM.’, e.g., IBM.CLOSE, IBM.OPEN, IBM.LOW, etc… This method returns a datastore_match object which can be used to walk the result set retrieving name, and other meta-data.

virtual tom::tsdb::datastore_match_sptr regex_name_search(const tom::observation &regex) = 0: datastore objects provide full extended posix regex search capabilities on the datastore. This allows for rich querying of the datastore based on time_series names which typically follow semantics to create naturally grouped objects, e.g., regex_name_search( “IBM..*” ); would return all objects starting with ‘IBM.’, e.g., IBM.CLOSE, IBM.OPEN, IBM.LOW, etc… This method returns a datastore_match object which can be used to walk the result set retrieving name, and other meta-data.

virtual void save_time_series(const tom::tsdb::time_series &ts, bool overwrite = false) = 0: save a time_series object. If saving changes to a time_series, users may use the time_series::save( bool overwrite = false ) method. This method is mainly useful for moving time_series objects from one datastore to another. This is fully supported between datastores with any and all persistence back-ends, so moving time_series from FAME to ORACLE to BDB, etc., is all perfectly legal and simple. If the object already exists in the datastore overwrite must be set to true, or an exception derivative of std::runtime_error will be thrown and must be caught.

virtual void set_description(const tom::observation&) = 0: set the description of the datastore object

virtual void set_documentation(const tom::observation&) = 0: set the documentation of the datastore object

Public Static Functions

static tom::calendars::calendar &get_calendar(unsigned int cal_t)

static unsigned int get_calendar_id(tom::calendars::calendar &cal)

Friends

friend class time_series

class time_series : public tom::collections::time_series

time_series derive from tom::collection::time_series adding the requirements needed for persistent management. These include a name, or identifier, alias_sets, data and aggregation information, user defined attributes, indication if the series is sparse, and several others.

Time_series are internally heavily templatized classes that have excellant runtime characteristics and typically amortized constant performance on basic operations like copying, and 0(N) on iterative operations like visiting all data observations.

Time_series are also garbage collected entities and may be passed through out a program without concern for memory management issues.

Finally, while there are concrete template classes, it is far easier to use the datastore::create_time_series(…) methods to create both time_series and sparse_series objects.

Subclassed by tom::tsdb::collections::time_series< T, NATIVE_TYPE >, tom::tsdb::sparse_series

Public Types

typedef std::map<tom::string, tom::string> attribute_map_t

typedef std::set<tom::string> attribute_set_t

typedef bool (tom::tsdb::datastore::* populate_data_func)(tom::collections::time_series &ts, const tom::string &name, tom::tsdb::native_data_type data_t, tom::calendars::calendar &cal, tom::calendars::date_int_type from, tom::calendars::date_int_type to)

Public Functions

inline time_series()

inline virtual ~time_series()

bool alias_set_touched() const: Check if anyone has accessed the alias_set. This is mainly useful for persistence back-ends who need to check if the alias_set should be checked for changes.

virtual bool exists() const: Does the time_series already exist in the datastore?

size_t get_added_aliases(alias_set &added) const: Get a count of the number of aliases added, and the added aliases added to the passed alias_set. This method is mainly useful for persistence back-ends/

virtual aggregation_type get_aggregation_type() const = 0: get the aggregation_type for the time_series object

virtual alias_set &get_alias_set(): get the alias_set for the time_series. this may then be queried and/or updated and will be saved when the time_series object is itself changed.

virtual const alias_set &get_alias_set() const: get the alias_set for the time_series. this may then be queried but not updated and no changes can be saved when the time_series object is itself changed.

inline const tom::String &get_attribute(const char *att_name, bool check_datastore = true) const: get a user defined attribute for the time_series object. Users may associate any type of observation with time_series objects using a unique key for the object. For instance, users may want to store a description of a time_series, which may later be retrieved with this method, e.g., descr = time_series::get_attribute( “description” );

inline const tom::String &get_attribute(const tom::observation &att_name, bool check_datastore = true) const: get a user defined attribute for the time_series object. Users may associate any type of observation with time_series objects using a unique key for the object. For instance, users may want to store a description of a time_series, which may later be retrieved with this method, e.g., descr = time_series::get_attribute( “description” );

const tom::String &get_attribute(const tom::String &att_name, bool check_datastore = true) const: get a user defined attribute for the time_series object. Users may associate any type of observation with time_series objects using a unique key for the object. For instance, users may want to store a description of a time_series, which may later be retrieved with this method, e.g., descr = time_series::get_attribute( “description” );

inline virtual const attribute_set_t &get_changed_attribute_names() const

virtual const tom::calendars::date_time &get_create_date_time() const = 0: get the date_time of the time_series objects creation within the datastore.

virtual const values::data_type &get_data_type() const = 0: get the data_type for the time_series object.

virtual tom::tsdb::datastore &get_datastore() const = 0: get the parent datastore for the time_series object.

size_t get_dropped_aliases(alias_set &dropped) const: Get a count of the number of aliases dropped, and the dropped aliases added to the passed alias_set. This method is mainly useful for persistence back-ends/

virtual tom::calendars::date_int_type get_first_dirty_date_int() const = 0: get the date_int_type for the earliest changed observation. This is mainly useful for persistence back-ends, but may be useful for you too.

virtual tom::calendars::date_int_type get_last_dirty_date_int() const = 0: get the date_int_type for the latest changed observation. This is mainly useful for persistence back-ends, but may be useful for you too.

virtual const tom::calendars::date_time &get_modify_date_time() const = 0: get the date_time of the time_series objects last modification within the datastore.

virtual const tom::string &get_name() const = 0: get the name or identifier for a time_series.

virtual const void *get_raw_data() const = 0

virtual bool is_sparse_series() const = 0: indicates if the time_series contains only sparse data, or data at near regular intervals

bool operator!=(const time_series &rhs) const: Check for time_series object inequality. This checks all facets of the time_series such as aliases, data, data type, etc.

bool operator==(const time_series &rhs) const: Check for time_series object equality. This checks all facets of the time_series such as aliases, data, data type, etc.

virtual void save(bool overwrite = false)

save the time_series object in the parent datastore. if overwrite is true, objects having the same name but different type, calendar, etc. will be overwritten by this time_series.

This method may throw a derivative of the std::runtime_error if persistence errors occur and hence should be wrapped in a try block for safety.

virtual void set_aggregation_type(aggregation_type) = 0: set the aggregation type for the time_series object

inline void set_attribute(const char *att_name, const char *att_value): set a user defined attribute for the time_series object. Users may associate any type of observation with time_series objects using a unique key for the object. For instance, users may want to store a description of a time_series, which may later be retrieved with the get_attribute method, e.g., time_series::set_attribute( “description”, “my favorite time-series” );

inline void set_attribute(const tom::observation &att_name, const tom::observation &att_value): set a user defined attribute for the time_series object. Users may associate any type of observation with time_series objects using a unique key for the object. For instance, users may want to store a description of a time_series, which may later be retrieved with the get_attribute method, e.g., time_series::set_attribute( “description”, “my favorite time-series” );

void set_attribute(const tom::String &att_name, const tom::String &att_value): set a user defined attribute for the time_series object. Users may associate any type of observation with time_series objects using a unique key for the object. For instance, users may want to store a description of a time_series, which may later be retrieved with the get_attribute method, e.g., time_series::set_attribute( “description”, “my favorite time-series” );

Friends

friend class ::tom::tsdb::datastore

class sparse_series : public virtual tom::tsdb::time_series 

Subclassed by tom::tsdb::collections::sparse_series< T, NATIVE_TYPE >

Public Functions

inline virtual ~sparse_series()

virtual bool get_fill_forward() const = 0

virtual bool get_ignore_missing_values() const = 0

virtual bool get_ignore_same_values() const = 0

virtual void set_fill_forward(bool b) = 0

virtual void set_ignore_missing_values(bool b) = 0

virtual void set_ignore_same_values(bool b) = 0