/*
- * Copyright 2001-2006 Internet2
+ * Copyright 2001-2007 Internet2
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* Generic data storage interface
*/
-#ifndef __xmltooling_storage_h__
+#if !defined(__xmltooling_storage_h__) && !defined(XMLTOOLING_LITE)
#define __xmltooling_storage_h__
#include <xmltooling/XMLObject.h>
* @param key null-terminated unique key of up to 255 bytes
* @param value null-terminated value of up to 255 bytes to store
* @param expiration an expiration timestamp, after which the record can be purged
+ * @return true iff record was inserted, false iff a duplicate was found
*
- * @throws IOException raised if errors occur in the insertion process
+ * @throws IOException raised if fatal errors occur in the insertion process
*/
- virtual void createString(const char* context, const char* key, const char* value, time_t expiration)=0;
+ virtual bool createString(const char* context, const char* key, const char* value, time_t expiration)=0;
/**
* Returns an existing "short" record from the storage service.
+ *
+ * <p>The version parameter can be set for "If-Modified-Since" semantics.
*
* @param context a storage context label
* @param key null-terminated unique key of up to 255 bytes
* @param pvalue location in which to return the record value
* @param pexpiration location in which to return the expiration timestamp
- * @return true iff a valid record exists and was returned
+ * @param version if > 0, only copy back data if newer than supplied version
+ * @return the version of the record read back, or 0 if no record exists
*
* @throws IOException raised if errors occur in the read process
*/
- virtual bool readString(const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL)=0;
+ virtual int readString(
+ const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL, int version=0
+ )=0;
/**
* Updates an existing "short" record in the storage service.
* @param key null-terminated unique key of up to 255 bytes
* @param value null-terminated value of up to 255 bytes to store, or NULL to leave alone
* @param expiration a new expiration timestamp, or 0 to leave alone
- * @return true iff the record exists and was updated
+ * @param version if > 0, only update if the current version matches this value
+ * @return 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)
*
* @throws IOException raised if errors occur in the update process
*/
- virtual bool updateString(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;
+ virtual int updateString(
+ const char* context, const char* key, const char* value=NULL, time_t expiration=0, int version=0
+ )=0;
/**
* Deletes an existing "short" record from the storage service.
* @param key null-terminated unique key of up to 255 bytes
* @param value null-terminated value of arbitrary length
* @param expiration an expiration timestamp, after which the record can be purged
+ * @return true iff record was inserted, false iff a duplicate was found
*
* @throws IOException raised if errors occur in the insertion process
*/
- virtual void createText(const char* context, const char* key, const char* value, time_t expiration)=0;
+ virtual bool createText(const char* context, const char* key, const char* value, time_t expiration)=0;
/**
* Returns an existing "long" record from the storage service.
+ *
+ * <p>The version parameter can be set for "If-Modified-Since" semantics.
*
* @param context a storage context label
* @param key null-terminated unique key of up to 255 bytes
* @param pvalue location in which to return the record value
* @param pexpiration location in which to return the expiration timestamp
- * @return true iff a valid record exists and was returned
+ * @param version if > 0, only copy back data if newer than supplied version
+ * @return the version of the record read back, or 0 if no record exists
*
* @throws IOException raised if errors occur in the read process
*/
- virtual bool readText(const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL)=0;
+ virtual int readText(
+ const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL, int version=0
+ )=0;
/**
* Updates an existing "long" record in the storage service.
* @param key null-terminated unique key of up to 255 bytes
* @param value null-terminated value of arbitrary length to store, or NULL to leave alone
* @param expiration a new expiration timestamp, or 0 to leave alone
- * @return true iff the record exists and was updated
+ * @param version if > 0, only update if the current version matches this value
+ * @return 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)
*
* @throws IOException raised if errors occur in the update process
*/
- virtual bool updateText(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;
+ virtual int updateText(
+ const char* context, const char* key, const char* value=NULL, time_t expiration=0, int version=0
+ )=0;
/**
* Deletes an existing "long" record from the storage service.
virtual void reap(const char* context)=0;
/**
+ * Updates the expiration time of all records in the context.
+ *
+ * @param context a storage context label
+ * @param expiration a new expiration timestamp
+ */
+ virtual void updateContext(const char* context, time_t expiration)=0;
+
+ /**
* Forcibly removes all records in a given context along with any
* associated resources devoted to maintaining the context.
*
void XMLTOOL_API registerStorageServices();
/** StorageService based on in-memory caching. */
- #define MEMORY_STORAGE_SERVICE "org.opensaml.xmlooling.MemoryStorageService"
+ #define MEMORY_STORAGE_SERVICE "Memory"
};
#endif /* __xmltooling_storage_h__ */