A class to represent a data storage mechanism. More...

#include <be_io_recordstore.h>

Classes
struct	Record

Public Types
enum class	Kind { BerkeleyDB , Archive , File , SQLite , Compressed , List , Default = BerkeleyDB }
	Possible types of RecordStore. More...

using	Record = Record

using	iterator = IO::RecordStoreIterator

Public Member Functions
virtual std::string	getDescription () const =0
	Obtain a textual description of the RecordStore. More...

virtual unsigned int	getCount () const =0
	Obtain the number of items in the RecordStore. More...

virtual std::string	getPathname () const =0
	Return the path name of the RecordStore. More...

virtual void	move (const std::string &pathname)=0
	Move the RecordStore. More...

virtual void	changeDescription (const std::string &description)=0
	Change the description of the RecordStore. More...

virtual uint64_t	getSpaceUsed () const =0
	Obtain real storage utilization. More...

virtual void	sync () const =0
	Synchronize the entire record store to persistent storage. More...

virtual void	insert (const std::string &key, const Memory::uint8Array &data)
	Insert a record into the store. More...

virtual void	insert (const std::string &key, const void *const data, const uint64_t size)=0
	Insert a record into the store. More...

virtual void	remove (const std::string &key)=0
	Remove a record from the store. More...

virtual Memory::uint8Array	read (const std::string &key) const =0
	Read a complete record from a store. More...

virtual void	replace (const std::string &key, const Memory::uint8Array &data)
	Replace a complete record in a RecordStore. More...

virtual void	replace (const std::string &key, const void *const data, const uint64_t size)
	Replace a complete record in a RecordStore. More...

virtual uint64_t	length (const std::string &key) const =0
	Return the length of a record. More...

virtual void	flush (const std::string &key) const =0
	Commit the record's data to storage. More...

virtual RecordStore::Record	sequence (int cursor=BE_RECSTORE_SEQ_NEXT)=0
	Sequence through a RecordStore, returning the key/data pairs. More...

virtual std::string	sequenceKey (int cursor=BE_RECSTORE_SEQ_NEXT)=0
	Sequence through a RecordStore, returning the key. More...

virtual void	setCursorAtKey (const std::string &key)=0
	Set the sequence cursor to an arbitrary position within the RecordStore, starting at key. More...

virtual bool	containsKey (const std::string &key) const
	Determines whether the RecordStore contains an element with the specified key. More...

virtual iterator	begin () noexcept

virtual iterator	end () noexcept

Static Public Member Functions
static bool	isRecordStore (const std::string &pathname)
	Determine if a location appears to be a RecordStore. More...

static std::shared_ptr< RecordStore >	openRecordStore (const std::string &pathname, IO::Mode mode=Mode::ReadOnly)
	Open an existing RecordStore and return a managed pointer to the the object representing that store. More...

static std::shared_ptr< RecordStore >	createRecordStore (const std::string &pathname, const std::string &description, const IO::RecordStore::Kind &kind)
	Create a new RecordStore and return a managed pointer to the the object representing that store. More...

static void	removeRecordStore (const std::string &pathname)
	Remove a RecordStore by deleting all persistant data associated with the store. More...

static void	mergeRecordStores (const std::string &mergePathname, const std::string &description, const IO::RecordStore::Kind &kind, const std::vector< std::string > &pathnames, const std::function< bool()> &interrupt=[]() {return(false);})
	Create a new RecordStore that contains the contents of several other RecordStores. More...

Static Public Attributes
static const std::string	INVALIDKEYCHARS
	The set of prohibited characters in a key: '/', '\', '*', '&'.

static const int	BE_RECSTORE_SEQ_START = 1
	Tell sequence() to sequence from beginning.

static const int	BE_RECSTORE_SEQ_NEXT = 2
	Tell sequence to sequence from current position.

Detailed Description

A class to represent a data storage mechanism.

A RecordStore is an abstraction that associates keys with a specific data item. Implementations of this abstraction can store the records in any format supported by the operating system, such as files or databases, rooted in the file system.

Certain characters are prohibited in the key string. See IO::RecordStore::INVALIDKEYCHARS. A key string cannot begin with the space character.

See also: IO::ArchiveRecordStore, IO::DBRecordStore, IO::FileRecordStore.

Member Enumeration Documentation

◆ Kind

enum class BiometricEvaluation::IO::RecordStore::Kind

strong

Possible types of RecordStore.

Enumerator
BerkeleyDB	DBRecordStore.
Archive	ArchiveRecordStore.
File	FileRecordStore.
SQLite	SQLiteRecordStore.
Compressed	CompressedRecordStore.
List	ListRecordStore.
Default	"Default" RecordStore kind

Member Function Documentation

◆ begin()

virtual iterator BiometricEvaluation::IO::RecordStore::begin ( )

virtualnoexcept

Returns: Iterator to the first record.

◆ changeDescription()

virtual void BiometricEvaluation::IO::RecordStore::changeDescription ( const std::string & description )

pure virtual

Change the description of the RecordStore.

Parameters

[in] description The new description.

Exceptions

Error::StrategyError An error occurred when using the underlying storage system.

◆ containsKey()

virtual bool BiometricEvaluation::IO::RecordStore::containsKey ( const std::string & key ) const

virtual

Determines whether the RecordStore contains an element with the specified key.

Parameters

key	The key to locate.

Returns: True if the RecordStore contains an element with the key, false otherwise.

◆ createRecordStore()

static std::shared_ptr< RecordStore > BiometricEvaluation::IO::RecordStore::createRecordStore	(	const std::string &	pathname,
		const std::string &	description,
		const IO::RecordStore::Kind &	kind
	)

static

Create a new RecordStore and return a managed pointer to the the object representing that store.

The allocated object will be automatically freed when the returned pointer goes out of scope. Applications should not delete the object.

Parameters

[in]	pathname	The directory of the store to be created.
[in]	description	The description of the store to be created.
[in]	kind	The kind of RecordStore to be created.

Returns: An managed pointer to the object representing the created store.

Exceptions

Error::ObjectDoesNotExist	The RecordStore does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ end()

virtual iterator BiometricEvaluation::IO::RecordStore::end ( )

virtualnoexcept

Returns: Iterator past the last record.

◆ flush()

virtual void BiometricEvaluation::IO::RecordStore::flush ( const std::string & key ) const

pure virtual

Commit the record's data to storage.

Parameters

[in] key The key of the record to be flushed.

Exceptions

Error::ObjectDoesNotExist	A record for the key does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ getCount()

virtual unsigned int BiometricEvaluation::IO::RecordStore::getCount ( ) const

pure virtual

Obtain the number of items in the RecordStore.

Returns: The number of items in the RecordStore.

◆ getDescription()

virtual std::string BiometricEvaluation::IO::RecordStore::getDescription ( ) const

pure virtual

Obtain a textual description of the RecordStore.

Returns: The RecordStore's description.

◆ getPathname()

virtual std::string BiometricEvaluation::IO::RecordStore::getPathname ( ) const

pure virtual

Return the path name of the RecordStore.

Returns: Where in the file system the RecordStore is located.

◆ getSpaceUsed()

virtual uint64_t BiometricEvaluation::IO::RecordStore::getSpaceUsed ( ) const

pure virtual

Obtain real storage utilization.

The amount of disk space used, for example. This is the actual space allocated by the underlying storage mechanism, in bytes.

Returns: The amount of backing storage used by the RecordStore.

Exceptions

Error::StrategyError An error occurred when using the underlying storage system.

◆ insert() [1/2]

virtual void BiometricEvaluation::IO::RecordStore::insert	(	const std::string &	key,
		const Memory::uint8Array &	data
	)

virtual

Insert a record into the store.

Parameters

[in]	key	The key of the record to be inserted.
[in]	data	The data for the record.

Exceptions

Error::ObjectExists	A record with the given key is already present.
Error::StrategyError	The RecordStore is opened read-only, or an error occurred when using the underlying storage system.

◆ insert() [2/2]

virtual void BiometricEvaluation::IO::RecordStore::insert	(	const std::string &	key,
		const void *const	data,
		const uint64_t	size
	)

pure virtual

Insert a record into the store.

Parameters

[in]	key	The key of the record to be inserted.
[in]	data	The data for the record.
[in]	size	The size of the record, in bytes.

Exceptions

Error::ObjectExists	A record with the given key is already present.
Error::StrategyError	The RecordStore is opened read-only, or an error occurred when using the underlying storage system.

◆ isRecordStore()

static bool BiometricEvaluation::IO::RecordStore::isRecordStore ( const std::string & pathname )

static

Determine if a location appears to be a RecordStore.

Parameters

pathname The path name of the location to check.

Returns: true if pathname appears to point to a RecordStore, false otherwise.

◆ length()

virtual uint64_t BiometricEvaluation::IO::RecordStore::length ( const std::string & key ) const

pure virtual

Return the length of a record.

Parameters

[in] key The key of the record.

Returns: The record length.

Exceptions

Error::ObjectDoesNotExist	A record for the key does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ mergeRecordStores()

static void BiometricEvaluation::IO::RecordStore::mergeRecordStores	(	const std::string &	mergePathname,
		const std::string &	description,
		const IO::RecordStore::Kind &	kind,
		const std::vector< std::string > &	pathnames,
		const std::function< bool()> &	interrupt = `[]() {return(false);}`
	)

static

Create a new RecordStore that contains the contents of several other RecordStores.

Parameters

[in]	mergePathname	The path name of the new RecordStore that will be created.
[in]	description	The text used to describe the new RecordStore.
[in]	kind	The kind of the new, merged RecordStore.
[in]	pathnames	Vector of path names to RecordStores to open. These are the RecordStores that will be merged to create the new RecordStore.
[in]	interrupt	A function to be called during long operations to determine whether to interrupt and return.

Exceptions

Error::ObjectExists	A RecordStore at mergePathname already exists.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ move()

virtual void BiometricEvaluation::IO::RecordStore::move ( const std::string & pathname )

pure virtual

Move the RecordStore.

The RecordStore can be moved to a new path in the file system.

Parameters

[in] pathname The new path of the RecordStore.

Exceptions

Error::StrategyError An error occurred when using the underlying storage system.

◆ openRecordStore()

static std::shared_ptr< RecordStore > BiometricEvaluation::IO::RecordStore::openRecordStore	(	const std::string &	pathname,
		IO::Mode	mode = `Mode::ReadOnly`
	)

static

Open an existing RecordStore and return a managed pointer to the the object representing that store.

Applications can open existing record stores without the need to know what type of RecordStore it is.

The allocated object will be automatically freed when the returned pointer goes out of scope. Applications should not delete the object.

Parameters

[in]	pathname	The path name of the store to be opened.
[in]	mode	The type of access a client of this RecordStore has.

Returns: An object representing the existing store.

Exceptions

Error::ObjectDoesNotExist	The RecordStore does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ read()

virtual Memory::uint8Array BiometricEvaluation::IO::RecordStore::read ( const std::string & key ) const

pure virtual

Read a complete record from a store.

The AutoArray will be resized to match the size of the data.

Parameters

[in] key The key of the record to be read.

Returns: The record associated with the key.

Exceptions

Error::ObjectDoesNotExist	A record for the key does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ remove()

virtual void BiometricEvaluation::IO::RecordStore::remove ( const std::string & key )

pure virtual

Remove a record from the store.

Parameters

[in] key The key of the record to be removed.

Exceptions

Error::ObjectDoesNotExist	A record for the key does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ removeRecordStore()

static void BiometricEvaluation::IO::RecordStore::removeRecordStore ( const std::string & pathname )

static

Remove a RecordStore by deleting all persistant data associated with the store.

Parameters

[in] pathname The name of the existing RecordStore.

Exceptions

Error::ObjectDoesNotExist	A record with the given key does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ replace() [1/2]

virtual void BiometricEvaluation::IO::RecordStore::replace	(	const std::string &	key,
		const Memory::uint8Array &	data
	)

virtual

Replace a complete record in a RecordStore.

Parameters

[in]	key	The key of the record to be replaced.
[in]	data	The data for the record.

Exceptions

Error::ObjectDoesNotExist	A record for the key does not exist.
Error::StrategyError	The RecordStore is opened read-only, or an error occurred when using the underlying storage system.

◆ replace() [2/2]

virtual void BiometricEvaluation::IO::RecordStore::replace	(	const std::string &	key,
		const void *const	data,
		const uint64_t	size
	)

virtual

Replace a complete record in a RecordStore.

Parameters

[in]	key	The key of the record to be replaced.
[in]	data	The data for the record.
[in]	size	The size of the record, in bytes.

Exceptions

Error::ObjectDoesNotExist	A record for the key does not exist.
Error::StrategyError	The RecordStore is opened read-only, or an error occurred when using the underlying storage system.

◆ sequence()

virtual RecordStore::Record BiometricEvaluation::IO::RecordStore::sequence ( int cursor = BE_RECSTORE_SEQ_NEXT )

pure virtual

Sequence through a RecordStore, returning the key/data pairs.

Sequencing means to start at some point in the store and return the record, then repeatedly calling the function to return the next record. The starting point is typically the first record, and is set to that when the RecordStore object is created. The starting point can be reset by calling this method with the cursor parameter set to BE_RECSTORE_SEQ_START.

Parameters

[in] cursor The location within the sequence of the key/data pair to return.

Returns: The record that is currently in sequence.

Exceptions

Error::ObjectDoesNotExist	End of sequencing.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ sequenceKey()

virtual std::string BiometricEvaluation::IO::RecordStore::sequenceKey ( int cursor = BE_RECSTORE_SEQ_NEXT )

pure virtual

Sequence through a RecordStore, returning the key.

Sequencing means to start at some point in the store and return the key, then repeatedly calling the function to return the next key. The starting point is typically the first record, and is set to that when the RecordStore object is created. The starting point can be reset by calling this method with the cursor parameter set to BE_RECSTORE_SEQ_START.

Parameters

[in] cursor The location within the sequence of the key/data pair to return.

Returns: The key of the currently sequenced record.

Exceptions

Error::ObjectDoesNotExist	End of sequencing.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ setCursorAtKey()

virtual void BiometricEvaluation::IO::RecordStore::setCursorAtKey ( const std::string & key )

pure virtual

Set the sequence cursor to an arbitrary position within the RecordStore, starting at key.

Key will be the first record returned from the next call to sequence().

Parameters

[in] key The key of the record which will be returned by the first subsequent call to sequence().

Exceptions

Error::ObjectDoesNotExist	A record for the key does not exist.
Error::StrategyError	An error occurred when using the underlying storage system.

◆ sync()

virtual void BiometricEvaluation::IO::RecordStore::sync ( ) const

pure virtual

Synchronize the entire record store to persistent storage.

Exceptions

Error::StrategyError An error occurred when using the underlying storage system.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ Kind

Member Function Documentation

◆ begin()

◆ changeDescription()

◆ containsKey()

◆ createRecordStore()

◆ end()

◆ flush()

◆ getCount()

◆ getDescription()

◆ getPathname()

◆ getSpaceUsed()

◆ insert() [1/2]

◆ insert() [2/2]

◆ isRecordStore()

◆ length()

◆ mergeRecordStores()

◆ move()

◆ openRecordStore()

◆ read()

◆ remove()

◆ removeRecordStore()

◆ replace() [1/2]

◆ replace() [2/2]

◆ sequence()

◆ sequenceKey()

◆ setCursorAtKey()

◆ sync()