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.

Public Member Functions

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=NULL, time_t *pexpiration=NULL, 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=NULL, 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=NULL, time_t *pexpiration=NULL, 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=NULL, 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.


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 of up to 255 bytes
value null-terminated value of up to 255 bytes to store
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 of up to 255 bytes
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 of up to 255 bytes
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 of up to 255 bytes
Returns:
true iff the record existed and was deleted
Exceptions:
IOException raised if errors occur in the deletion process

virtual int xmltooling::StorageService::readString ( const char *  context,
const char *  key,
std::string *  pvalue = NULL,
time_t *  pexpiration = NULL,
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 of up to 255 bytes
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 int xmltooling::StorageService::readText ( const char *  context,
const char *  key,
std::string *  pvalue = NULL,
time_t *  pexpiration = NULL,
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 of up to 255 bytes
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 = NULL,
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 of up to 255 bytes
value null-terminated value of up to 255 bytes to store, or NULL 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 = NULL,
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 of up to 255 bytes
value null-terminated value of arbitrary length to store, or NULL 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 Mon Oct 19 14:18:35 2009 for xmltooling by  doxygen 1.4.7