xmltooling::StorageService Class Reference

Generic data storage facility for use by services that require some degree of persistence. More...

#include <xmltooling/util/StorageService.h>

List of all members.

Classes

class  Capabilities

Public Member Functions

virtual const CapabilitiesgetCapabilities () const
 Returns the capabilities of the underlying service.
virtual bool createString (const char *context, const char *key, const char *value, time_t expiration)=0
 Creates a new "short" record in the storage service.
virtual int readString (const char *context, const char *key, std::string *pvalue=0, time_t *pexpiration=0, int version=0)=0
 Returns an existing "short" record from the storage service.
virtual int updateString (const char *context, const char *key, const char *value=0, time_t expiration=0, int version=0)=0
 Updates an existing "short" record in the storage service.
virtual bool deleteString (const char *context, const char *key)=0
 Deletes an existing "short" record from the storage service.
virtual bool createText (const char *context, const char *key, const char *value, time_t expiration)=0
 Creates a new "long" record in the storage service.
virtual int readText (const char *context, const char *key, std::string *pvalue=0, time_t *pexpiration=0, int version=0)=0
 Returns an existing "long" record from the storage service.
virtual int updateText (const char *context, const char *key, const char *value=0, time_t expiration=0, int version=0)=0
 Updates an existing "long" record in the storage service.
virtual bool deleteText (const char *context, const char *key)=0
 Deletes an existing "long" record from the storage service.
virtual void reap (const char *context)=0
 Manually trigger a cleanup of expired records.
virtual void updateContext (const char *context, time_t expiration)=0
 Updates the expiration time of all records in the context.
virtual void deleteContext (const char *context)=0
 Forcibly removes all records in a given context along with any associated resources devoted to maintaining the context.

Detailed Description

Generic data storage facility for use by services that require some degree of persistence.

Implementations will vary in how much persistence they can supply.

Storage is divided into "contexts" identified by a string label. Keys need to be unique only within a given context, so multiple components can share a single storage service safely as long as they use different labels.

The allowable sizes for contexts, keys, and short values can vary and be reported by the implementation to callers, but MUST be at least 255 bytes.


Member Function Documentation

virtual bool xmltooling::StorageService::createString ( const char *  context,
const char *  key,
const char *  value,
time_t  expiration 
) [pure virtual]

Creates a new "short" record in the storage service.

Parameters:
context a storage context label
key null-terminated unique key
value null-terminated value
expiration an expiration timestamp, after which the record can be purged
Returns:
true iff record was inserted, false iff a duplicate was found
Exceptions:
IOException raised if fatal errors occur in the insertion process
virtual bool xmltooling::StorageService::createText ( const char *  context,
const char *  key,
const char *  value,
time_t  expiration 
) [pure virtual]

Creates a new "long" record in the storage service.

Parameters:
context a storage context label
key null-terminated unique key
value null-terminated value of arbitrary length
expiration an expiration timestamp, after which the record can be purged
Returns:
true iff record was inserted, false iff a duplicate was found
Exceptions:
IOException raised if errors occur in the insertion process
virtual void xmltooling::StorageService::deleteContext ( const char *  context  )  [pure virtual]

Forcibly removes all records in a given context along with any associated resources devoted to maintaining the context.

Parameters:
context a storage context label
virtual bool xmltooling::StorageService::deleteString ( const char *  context,
const char *  key 
) [pure virtual]

Deletes an existing "short" record from the storage service.

Parameters:
context a storage context label
key null-terminated unique key
Returns:
true iff the record existed and was deleted
Exceptions:
IOException raised if errors occur in the deletion process
virtual bool xmltooling::StorageService::deleteText ( const char *  context,
const char *  key 
) [pure virtual]

Deletes an existing "long" record from the storage service.

Parameters:
context a storage context label
key null-terminated unique key
Returns:
true iff the record existed and was deleted
Exceptions:
IOException raised if errors occur in the deletion process
virtual const Capabilities& xmltooling::StorageService::getCapabilities (  )  const [virtual]

Returns the capabilities of the underlying service.

If implementations support only the 255 character minimum, the default implementation of this method will suffice.

Returns:
a reference to an interface to access the service's capabilities
virtual int xmltooling::StorageService::readString ( const char *  context,
const char *  key,
std::string *  pvalue = 0,
time_t *  pexpiration = 0,
int  version = 0 
) [pure virtual]

Returns an existing "short" record from the storage service.

The version parameter can be set for "If-Modified-Since" semantics.

Parameters:
context a storage context label
key null-terminated unique key
pvalue location in which to return the record value
pexpiration location in which to return the expiration timestamp
version if > 0, only copy back data if newer than supplied version (the expiration time is copied back regardless)
Returns:
the version of the record read back, or 0 if no record exists
Exceptions:
IOException raised if errors occur in the read process
virtual int xmltooling::StorageService::readText ( const char *  context,
const char *  key,
std::string *  pvalue = 0,
time_t *  pexpiration = 0,
int  version = 0 
) [pure virtual]

Returns an existing "long" record from the storage service.

The version parameter can be set for "If-Modified-Since" semantics.

Parameters:
context a storage context label
key null-terminated unique key
pvalue location in which to return the record value
pexpiration location in which to return the expiration timestamp
version if > 0, only copy back data if newer than supplied version
Returns:
the version of the record read back, or 0 if no record exists
Exceptions:
IOException raised if errors occur in the read process
virtual void xmltooling::StorageService::reap ( const char *  context  )  [pure virtual]

Manually trigger a cleanup of expired records.

The method MAY return without guaranteeing that cleanup has already occurred.

Parameters:
context a storage context label
virtual void xmltooling::StorageService::updateContext ( const char *  context,
time_t  expiration 
) [pure virtual]

Updates the expiration time of all records in the context.

Parameters:
context a storage context label
expiration a new expiration timestamp
virtual int xmltooling::StorageService::updateString ( const char *  context,
const char *  key,
const char *  value = 0,
time_t  expiration = 0,
int  version = 0 
) [pure virtual]

Updates an existing "short" record in the storage service.

Parameters:
context a storage context label
key null-terminated unique key
value null-terminated value to store, or nullptr to leave alone
expiration a new expiration timestamp, or 0 to leave alone
version if > 0, only update if the current version matches this value
Returns:
the version of the record after update, 0 if no record exists, or -1 if the version parameter is non-zero and does not match the current version before update (so the caller is out of sync)
Exceptions:
IOException raised if errors occur in the update process
virtual int xmltooling::StorageService::updateText ( const char *  context,
const char *  key,
const char *  value = 0,
time_t  expiration = 0,
int  version = 0 
) [pure virtual]

Updates an existing "long" record in the storage service.

Parameters:
context a storage context label
key null-terminated unique key
value null-terminated value of arbitrary length to store, or nullptr to leave alone
expiration a new expiration timestamp, or 0 to leave alone
version if > 0, only update if the current version matches this value
Returns:
the version of the record after update, 0 if no record exists, or -1 if the version parameter is non-zero and does not match the current version before update (so the caller is out of sync)
Exceptions:
IOException raised if errors occur in the update process

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

Generated on 24 Jan 2020 for xmltooling by  doxygen 1.6.1