xmltooling  3.2.0
xmltooling::StorageService Class Referenceabstract

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

#include <xmltooling/util/StorageService.h>

Classes

class  Capabilities
 

Public Member Functions

virtual const CapabilitiesgetCapabilities () const
 Returns the capabilities of the underlying service. More...
 
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. More...
 
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. More...
 
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. More...
 
virtual bool deleteString (const char *context, const char *key)=0
 Deletes an existing "short" record from the storage service. More...
 
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. More...
 
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. More...
 
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. More...
 
virtual bool deleteText (const char *context, const char *key)=0
 Deletes an existing "long" record from the storage service. More...
 
virtual void reap (const char *context)=0
 Manually trigger a cleanup of expired records. More...
 
virtual void updateContext (const char *context, time_t expiration)=0
 Updates the expiration time of all records in the context. More...
 
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. More...
 

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

◆ createString()

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
contexta storage context label
keynull-terminated unique key
valuenull-terminated value
expirationan expiration timestamp, after which the record can be purged
Returns
true iff record was inserted, false iff a duplicate was found
Exceptions
IOExceptionraised if fatal errors occur in the insertion process

◆ createText()

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
contexta storage context label
keynull-terminated unique key
valuenull-terminated value of arbitrary length
expirationan expiration timestamp, after which the record can be purged
Returns
true iff record was inserted, false iff a duplicate was found
Exceptions
IOExceptionraised if errors occur in the insertion process

◆ deleteContext()

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
contexta storage context label

◆ deleteString()

virtual bool xmltooling::StorageService::deleteString ( const char *  context,
const char *  key 
)
pure virtual

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

Parameters
contexta storage context label
keynull-terminated unique key
Returns
true iff the record existed and was deleted
Exceptions
IOExceptionraised if errors occur in the deletion process

◆ deleteText()

virtual bool xmltooling::StorageService::deleteText ( const char *  context,
const char *  key 
)
pure virtual

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

Parameters
contexta storage context label
keynull-terminated unique key
Returns
true iff the record existed and was deleted
Exceptions
IOExceptionraised if errors occur in the deletion process

◆ getCapabilities()

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

◆ readString()

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
contexta storage context label
keynull-terminated unique key
pvaluelocation in which to return the record value
pexpirationlocation in which to return the expiration timestamp
versionif > 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
IOExceptionraised if errors occur in the read process

◆ readText()

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
contexta storage context label
keynull-terminated unique key
pvaluelocation in which to return the record value
pexpirationlocation in which to return the expiration timestamp
versionif > 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
IOExceptionraised if errors occur in the read process

◆ reap()

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
contexta storage context label

◆ updateContext()

virtual void xmltooling::StorageService::updateContext ( const char *  context,
time_t  expiration 
)
pure virtual

Updates the expiration time of all records in the context.

Parameters
contexta storage context label
expirationa new expiration timestamp

◆ updateString()

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
contexta storage context label
keynull-terminated unique key
valuenull-terminated value to store, or nullptr to leave alone
expirationa new expiration timestamp, or 0 to leave alone
versionif > 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
IOExceptionraised if errors occur in the update process

◆ updateText()

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
contexta storage context label
keynull-terminated unique key
valuenull-terminated value of arbitrary length to store, or nullptr to leave alone
expirationa new expiration timestamp, or 0 to leave alone
versionif > 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
IOExceptionraised if errors occur in the update process

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