xmltooling/util/StorageService.h

   1 /*\r
   2  *  Copyright 2001-2006 Internet2\r
   3  * \r
   4  * Licensed under the Apache License, Version 2.0 (the "License");\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  *\r
   8  *     http://www.apache.org/licenses/LICENSE-2.0\r
   9  *\r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an "AS IS" BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  */\r
  16 \r
  17 /**\r
  18  * @file xmltooling/util/StorageService.h\r
  19  * \r
  20  * Generic data storage facility for use by services that require persistence.\r
  21  */\r
  22 \r
  23 #ifndef __xmltooling_storage_h__\r
  24 #define __xmltooling_storage_h__\r
  25 \r
  26 #include <xmltooling/XMLObject.h>\r
  27 \r
  28 #include <ctime>\r
  29 \r
  30 namespace xmltooling {\r
  31 \r
  32     /**\r
  33      * Generic data storage facility for use by services that require persistence.\r
  34      */\r
  35     class XMLTOOL_API StorageService\r
  36     {\r
  37         MAKE_NONCOPYABLE(StorageService);\r
  38     public:\r
  39         virtual ~StorageService() {}\r
  40         \r
  41         /**\r
  42          * A "context" for accessing a StorageService instance.\r
  43          * Handles are created and freed using the StorageService interface,\r
  44          * and can be kept for the life of the service, and shared by multiple\r
  45          * threads.\r
  46          */\r
  47         class XMLTOOL_API StorageHandle {\r
  48             MAKE_NONCOPYABLE(StorageHandle);\r
  49             friend class XMLTOOL_API StorageService;\r
  50         public:\r
  51             virtual ~StorageHandle() {}\r
  52         protected:\r
  53             StorageHandle(StorageService* storage) : m_storage(storage) {}\r
  54             StorageService* m_storage;\r
  55         };\r
  56         \r
  57         \r
  58         /**\r
  59          * Returns a new handle for the storage service.\r
  60          * The caller <strong>MUST</strong> delete the handle\r
  61          * before freeing the StorageService itself.\r
  62          * \r
  63          * @return  a new handle\r
  64          */\r
  65         virtual StorageHandle* createHandle()=0;\r
  66         \r
  67         /**\r
  68          * Creates a new "short" record in the storage service.\r
  69          * \r
  70          * @param handle        a valid storage handle\r
  71          * @param key           null-terminated unique key of up to 255 bytes\r
  72          * @param value         null-terminated value of up to 255 bytes to store\r
  73          * @param expiration    an expiration timestamp, after which the record can be purged\r
  74          * \r
  75          * @throws IOException  raised if errors occur in the insertion process \r
  76          */\r
  77         virtual void createString(StorageHandle* handle, const char* key, const char* value, time_t expiration)=0;\r
  78         \r
  79         /**\r
  80          * Returns an existing "short" record from the storage service.\r
  81          * \r
  82          * @param handle        a valid storage handle\r
  83          * @param key           null-terminated unique key of up to 255 bytes\r
  84          * @param value         location in which to return the record value\r
  85          * @param modifiedSince the record should not be returned if unmodified since this time,\r
  86          *  or 0 to always return\r
  87          * @return  true iff the record exists and was returned (based on the modifiedSince value)   \r
  88          * \r
  89          * @throws IOException  raised if errors occur in the read process \r
  90          */\r
  91         virtual bool readString(StorageHandle* handle, const char* key, std::string& value, time_t modifiedSince=0)=0;\r
  92 \r
  93         /**\r
  94          * Updates an existing "short" record in the storage service.\r
  95          * \r
  96          * @param handle        a valid storage handle\r
  97          * @param key           null-terminated unique key of up to 255 bytes\r
  98          * @param value         null-terminated value of up to 255 bytes to store, or NULL to leave alone\r
  99          * @param expiration    a new expiration timestamp, or 0 to leave alone\r
 100          * @return true iff the record exists and was updated\r
 101          *    \r
 102          * @throws IOException  raised if errors occur in the update process \r
 103          */\r
 104         virtual bool updateString(StorageHandle* handle, const char* key, const char* value=NULL, time_t expiration=0)=0;\r
 105         \r
 106         /**\r
 107          * Deletes an existing "short" record from the storage service.\r
 108          * \r
 109          * @param handle        a valid storage handle\r
 110          * @param key           null-terminated unique key of up to 255 bytes\r
 111          * @return true iff the record existed and was deleted\r
 112          *    \r
 113          * @throws IOException  raised if errors occur in the deletion process \r
 114          */\r
 115         virtual bool deleteString(StorageHandle* handle, const char* key)=0;\r
 116         \r
 117         /**\r
 118          * Creates a new "long" record in the storage service.\r
 119          * \r
 120          * @param handle        a valid storage handle\r
 121          * @param key           null-terminated unique key of up to 255 bytes\r
 122          * @param value         null-terminated value of arbitrary length\r
 123          * @param expiration    an expiration timestamp, after which the record can be purged\r
 124          * \r
 125          * @throws IOException  raised if errors occur in the insertion process \r
 126          */\r
 127         virtual void createText(StorageHandle* handle, const char* key, const char* value, time_t expiration)=0;\r
 128         \r
 129         /**\r
 130          * Returns an existing "long" record from the storage service.\r
 131          * \r
 132          * @param handle        a valid storage handle\r
 133          * @param key           null-terminated unique key of up to 255 bytes\r
 134          * @param value         location in which to return the record value\r
 135          * @param modifiedSince the record should not be returned if unmodified since this time,\r
 136          *  or 0 to always return\r
 137          * @return  true iff the record exists and was returned (based on the modifiedSince value)\r
 138          *    \r
 139          * @throws IOException  raised if errors occur in the read process \r
 140          */\r
 141         virtual bool readText(StorageHandle* handle, const char* key, std::string& value, time_t modifiedSince=0)=0;\r
 142 \r
 143         /**\r
 144          * Updates an existing "long" record in the storage service.\r
 145          * \r
 146          * @param handle        a valid storage handle\r
 147          * @param key           null-terminated unique key of up to 255 bytes\r
 148          * @param value         null-terminated value of arbitrary length to store, or NULL to leave alone\r
 149          * @param expiration    a new expiration timestamp, or 0 to leave alone\r
 150          * @return true iff the record exists and was updated\r
 151          *    \r
 152          * @throws IOException  raised if errors occur in the update process \r
 153          */\r
 154         virtual bool updateText(StorageHandle* handle, const char* key, const char* value=NULL, time_t expiration=0)=0;\r
 155         \r
 156         /**\r
 157          * Deletes an existing "long" record from the storage service.\r
 158          * \r
 159          * @param handle        a valid storage handle\r
 160          * @param key           null-terminated unique key of up to 255 bytes\r
 161          * @return true iff the record existed and was deleted\r
 162          *    \r
 163          * @throws IOException  raised if errors occur in the deletion process \r
 164          */\r
 165         virtual bool deleteText(StorageHandle* handle, const char* key)=0;\r
 166         \r
 167         /**\r
 168          * Manually trigger a cleanup of expired records.\r
 169          * The method <strong>MAY</strong> return without guaranteeing that\r
 170          * cleanup has already occurred.\r
 171          * \r
 172          * @param handle        a valid storage handle\r
 173          */\r
 174         virtual void reap(StorageHandle* handle)=0;\r
 175 \r
 176     protected:\r
 177         StorageService() {}\r
 178         \r
 179         virtual bool isValid(StorageHandle* handle) {\r
 180             return this == (handle ? handle->m_storage : NULL);\r
 181         }\r
 182     };\r
 183 \r
 184     /**\r
 185      * Registers StorageService classes into the runtime.\r
 186      */\r
 187     void XMLTOOL_API registerStorageServices();\r
 188 \r
 189     /** StorageService based on in-memory caching. */\r
 190     #define MEMORY_STORAGE_SERVICE  "org.opensaml.xmlooling.MemoryStorageService"\r
 191 };\r
 192 \r
 193 #endif /* __xmltooling_storage_h__ */\r