/**\r
* @file xmltooling/util/StorageService.h\r
* \r
- * Generic data storage facility for use by services that require persistence.\r
+ * Generic data storage interface\r
*/\r
\r
#ifndef __xmltooling_storage_h__\r
namespace xmltooling {\r
\r
/**\r
- * Generic data storage facility for use by services that require persistence.\r
+ * Generic data storage facility for use by services that require\r
+ * some degree of persistence. Implementations will vary in how much\r
+ * persistence they can supply.\r
+ * \r
+ * <p>Storage is divided into "contexts" identified by a string label.\r
+ * Keys need to be unique only within a given context, so multiple\r
+ * components can share a single storage service safely as long as they\r
+ * use different labels.\r
*/\r
class XMLTOOL_API StorageService\r
{\r
virtual ~StorageService() {}\r
\r
/**\r
- * A "context" for accessing a StorageService instance.\r
- * Handles are created and freed using the StorageService interface,\r
- * and can be kept for the life of the service, and shared by multiple\r
- * threads.\r
- */\r
- class XMLTOOL_API StorageHandle {\r
- MAKE_NONCOPYABLE(StorageHandle);\r
- friend class XMLTOOL_API StorageService;\r
- public:\r
- virtual ~StorageHandle() {}\r
- protected:\r
- StorageHandle(StorageService* storage) : m_storage(storage) {}\r
- StorageService* m_storage;\r
- };\r
- \r
- \r
- /**\r
- * Returns a new handle for the storage service.\r
- * The caller <strong>MUST</strong> delete the handle\r
- * before freeing the StorageService itself.\r
- * \r
- * @return a new handle\r
- */\r
- virtual StorageHandle* createHandle()=0;\r
- \r
- /**\r
* Creates a new "short" record in the storage service.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
* @param key null-terminated unique key of up to 255 bytes\r
* @param value null-terminated value of up to 255 bytes to store\r
* @param expiration an expiration timestamp, after which the record can be purged\r
* \r
* @throws IOException raised if errors occur in the insertion process \r
*/\r
- virtual void createString(StorageHandle* handle, const char* key, const char* value, time_t expiration)=0;\r
+ virtual void createString(const char* context, const char* key, const char* value, time_t expiration)=0;\r
\r
/**\r
* Returns an existing "short" record from the storage service.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
* @param key null-terminated unique key of up to 255 bytes\r
* @param value location in which to return the record value\r
* @param modifiedSince the record should not be returned if unmodified since this time,\r
* \r
* @throws IOException raised if errors occur in the read process \r
*/\r
- virtual bool readString(StorageHandle* handle, const char* key, std::string& value, time_t modifiedSince=0)=0;\r
+ virtual bool readString(const char* context, const char* key, std::string& value, time_t modifiedSince=0)=0;\r
\r
/**\r
* Updates an existing "short" record in the storage service.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
* @param key null-terminated unique key of up to 255 bytes\r
* @param value null-terminated value of up to 255 bytes to store, or NULL to leave alone\r
* @param expiration a new expiration timestamp, or 0 to leave alone\r
* \r
* @throws IOException raised if errors occur in the update process \r
*/\r
- virtual bool updateString(StorageHandle* handle, const char* key, const char* value=NULL, time_t expiration=0)=0;\r
+ virtual bool updateString(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;\r
\r
/**\r
* Deletes an existing "short" record from the storage service.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
* @param key null-terminated unique key of up to 255 bytes\r
* @return true iff the record existed and was deleted\r
* \r
* @throws IOException raised if errors occur in the deletion process \r
*/\r
- virtual bool deleteString(StorageHandle* handle, const char* key)=0;\r
+ virtual bool deleteString(const char* context, const char* key)=0;\r
\r
/**\r
* Creates a new "long" record in the storage service.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
* @param key null-terminated unique key of up to 255 bytes\r
* @param value null-terminated value of arbitrary length\r
* @param expiration an expiration timestamp, after which the record can be purged\r
* \r
* @throws IOException raised if errors occur in the insertion process \r
*/\r
- virtual void createText(StorageHandle* handle, const char* key, const char* value, time_t expiration)=0;\r
+ virtual void createText(const char* context, const char* key, const char* value, time_t expiration)=0;\r
\r
/**\r
* Returns an existing "long" record from the storage service.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
* @param key null-terminated unique key of up to 255 bytes\r
* @param value location in which to return the record value\r
* @param modifiedSince the record should not be returned if unmodified since this time,\r
* \r
* @throws IOException raised if errors occur in the read process \r
*/\r
- virtual bool readText(StorageHandle* handle, const char* key, std::string& value, time_t modifiedSince=0)=0;\r
+ virtual bool readText(const char* context, const char* key, std::string& value, time_t modifiedSince=0)=0;\r
\r
/**\r
* Updates an existing "long" record in the storage service.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
* @param key null-terminated unique key of up to 255 bytes\r
* @param value null-terminated value of arbitrary length to store, or NULL to leave alone\r
* @param expiration a new expiration timestamp, or 0 to leave alone\r
* \r
* @throws IOException raised if errors occur in the update process \r
*/\r
- virtual bool updateText(StorageHandle* handle, const char* key, const char* value=NULL, time_t expiration=0)=0;\r
+ virtual bool updateText(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;\r
\r
/**\r
* Deletes an existing "long" record from the storage service.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
* @param key null-terminated unique key of up to 255 bytes\r
* @return true iff the record existed and was deleted\r
* \r
* @throws IOException raised if errors occur in the deletion process \r
*/\r
- virtual bool deleteText(StorageHandle* handle, const char* key)=0;\r
+ virtual bool deleteText(const char* context, const char* key)=0;\r
\r
/**\r
* Manually trigger a cleanup of expired records.\r
* The method <strong>MAY</strong> return without guaranteeing that\r
* cleanup has already occurred.\r
* \r
- * @param handle a valid storage handle\r
+ * @param context a storage context label\r
+ */\r
+ virtual void reap(const char* context)=0;\r
+ \r
+ /**\r
+ * Forcibly removes all records in a given context along with any\r
+ * associated resources devoted to maintaining the context.\r
+ * \r
+ * @param context a storage context label\r
*/\r
- virtual void reap(StorageHandle* handle)=0;\r
+ virtual void deleteContext(const char* context)=0;\r
\r
protected:\r
StorageService() {}\r
- \r
- virtual bool isValid(StorageHandle* handle) {\r
- return this == (handle ? handle->m_storage : NULL);\r
- }\r
};\r
\r
/**\r
projects / shibboleth / cpp-xmltooling.git / blobdiff