xmltooling 3.0.4

Classes | Public Member Functions | List of all members
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 Capabilities & | getCapabilities () 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

  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

## ◆ 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

  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

## ◆ 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

  context | a 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

  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

## ◆ deleteText()

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

## ◆ 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

  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

## ◆ 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

  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

## ◆ 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

  context | a 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

  context | a storage context label
  expiration | a 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

  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

## ◆ 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

  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:

- xmltooling/util/StorageService.h