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 interface\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\r
  34      * some degree of persistence. Implementations will vary in how much\r
  35      * persistence they can supply.\r
  36      * \r
  37      * <p>Storage is divided into "contexts" identified by a string label.\r
  38      * Keys need to be unique only within a given context, so multiple\r
  39      * components can share a single storage service safely as long as they\r
  40      * use different labels.\r
  41      */\r
  42     class XMLTOOL_API StorageService\r
  43     {\r
  44         MAKE_NONCOPYABLE(StorageService);\r
  45     public:\r
  46         virtual ~StorageService() {}\r
  47         \r
  48         /**\r
  49          * Creates a new "short" record in the storage service.\r
  50          * \r
  51          * @param context       a storage context label\r
  52          * @param key           null-terminated unique key of up to 255 bytes\r
  53          * @param value         null-terminated value of up to 255 bytes to store\r
  54          * @param expiration    an expiration timestamp, after which the record can be purged\r
  55          * \r
  56          * @throws IOException  raised if errors occur in the insertion process \r
  57          */\r
  58         virtual void createString(const char* context, const char* key, const char* value, time_t expiration)=0;\r
  59         \r
  60         /**\r
  61          * Returns an existing "short" record from the storage service.\r
  62          * \r
  63          * @param context       a storage context label\r
  64          * @param key           null-terminated unique key of up to 255 bytes\r
  65          * @param value         location in which to return the record value\r
  66          * @param modifiedSince the record should not be returned if unmodified since this time,\r
  67          *  or 0 to always return\r
  68          * @return  true iff the record exists and was returned (based on the modifiedSince value)   \r
  69          * \r
  70          * @throws IOException  raised if errors occur in the read process \r
  71          */\r
  72         virtual bool readString(const char* context, const char* key, std::string& value, time_t modifiedSince=0)=0;\r
  73 \r
  74         /**\r
  75          * Updates an existing "short" record in the storage service.\r
  76          * \r
  77          * @param context       a storage context label\r
  78          * @param key           null-terminated unique key of up to 255 bytes\r
  79          * @param value         null-terminated value of up to 255 bytes to store, or NULL to leave alone\r
  80          * @param expiration    a new expiration timestamp, or 0 to leave alone\r
  81          * @return true iff the record exists and was updated\r
  82          *    \r
  83          * @throws IOException  raised if errors occur in the update process \r
  84          */\r
  85         virtual bool updateString(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;\r
  86         \r
  87         /**\r
  88          * Deletes an existing "short" record from the storage service.\r
  89          * \r
  90          * @param context       a storage context label\r
  91          * @param key           null-terminated unique key of up to 255 bytes\r
  92          * @return true iff the record existed and was deleted\r
  93          *    \r
  94          * @throws IOException  raised if errors occur in the deletion process \r
  95          */\r
  96         virtual bool deleteString(const char* context, const char* key)=0;\r
  97         \r
  98         /**\r
  99          * Creates a new "long" record in the storage service.\r
 100          * \r
 101          * @param context       a storage context label\r
 102          * @param key           null-terminated unique key of up to 255 bytes\r
 103          * @param value         null-terminated value of arbitrary length\r
 104          * @param expiration    an expiration timestamp, after which the record can be purged\r
 105          * \r
 106          * @throws IOException  raised if errors occur in the insertion process \r
 107          */\r
 108         virtual void createText(const char* context, const char* key, const char* value, time_t expiration)=0;\r
 109         \r
 110         /**\r
 111          * Returns an existing "long" record from the storage service.\r
 112          * \r
 113          * @param context       a storage context label\r
 114          * @param key           null-terminated unique key of up to 255 bytes\r
 115          * @param value         location in which to return the record value\r
 116          * @param modifiedSince the record should not be returned if unmodified since this time,\r
 117          *  or 0 to always return\r
 118          * @return  true iff the record exists and was returned (based on the modifiedSince value)\r
 119          *    \r
 120          * @throws IOException  raised if errors occur in the read process \r
 121          */\r
 122         virtual bool readText(const char* context, const char* key, std::string& value, time_t modifiedSince=0)=0;\r
 123 \r
 124         /**\r
 125          * Updates an existing "long" record in the storage service.\r
 126          * \r
 127          * @param context       a storage context label\r
 128          * @param key           null-terminated unique key of up to 255 bytes\r
 129          * @param value         null-terminated value of arbitrary length to store, or NULL to leave alone\r
 130          * @param expiration    a new expiration timestamp, or 0 to leave alone\r
 131          * @return true iff the record exists and was updated\r
 132          *    \r
 133          * @throws IOException  raised if errors occur in the update process \r
 134          */\r
 135         virtual bool updateText(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;\r
 136         \r
 137         /**\r
 138          * Deletes an existing "long" record from the storage service.\r
 139          * \r
 140          * @param context       a storage context label\r
 141          * @param key           null-terminated unique key of up to 255 bytes\r
 142          * @return true iff the record existed and was deleted\r
 143          *    \r
 144          * @throws IOException  raised if errors occur in the deletion process \r
 145          */\r
 146         virtual bool deleteText(const char* context, const char* key)=0;\r
 147         \r
 148         /**\r
 149          * Manually trigger a cleanup of expired records.\r
 150          * The method <strong>MAY</strong> return without guaranteeing that\r
 151          * cleanup has already occurred.\r
 152          * \r
 153          * @param context       a storage context label\r
 154          */\r
 155         virtual void reap(const char* context)=0;\r
 156         \r
 157         /**\r
 158          * Forcibly removes all records in a given context along with any\r
 159          * associated resources devoted to maintaining the context.\r
 160          * \r
 161          * @param context       a storage context label\r
 162          */\r
 163         virtual void deleteContext(const char* context)=0;\r
 164 \r
 165     protected:\r
 166         StorageService() {}\r
 167     };\r
 168 \r
 169     /**\r
 170      * Registers StorageService classes into the runtime.\r
 171      */\r
 172     void XMLTOOL_API registerStorageServices();\r
 173 \r
 174     /** StorageService based on in-memory caching. */\r
 175     #define MEMORY_STORAGE_SERVICE  "org.opensaml.xmlooling.MemoryStorageService"\r
 176 };\r
 177 \r
 178 #endif /* __xmltooling_storage_h__ */\r