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     protected:\r
  39         StorageService() {}\r
  40         \r
  41     public:\r
  42         virtual ~StorageService() {}\r
  43         \r
  44         /**\r
  45          * Creates a new "short" record in the storage service.\r
  46          * \r
  47          * @param key           null-terminated unique key of up to 255 bytes\r
  48          * @param value         null-terminated value of up to 255 bytes to store\r
  49          * @param expiration    an expiration timestamp, after which the record can be purged\r
  50          * \r
  51          * @throws IOException  raised if errors occur in the insertion process \r
  52          */\r
  53         virtual void createString(const char* key, const char* value, time_t expiration)=0;\r
  54         \r
  55         /**\r
  56          * Returns an existing "short" record from the storage service.\r
  57          * \r
  58          * @param key           null-terminated unique key of up to 255 bytes\r
  59          * @param value         location in which to return the record value\r
  60          * @param modifiedSince the record should not be returned if unmodified since this time,\r
  61          *  or 0 to always return\r
  62          * @return  true iff the record exists and was returned (based on the modifiedSince value)   \r
  63          * \r
  64          * @throws IOException  raised if errors occur in the read process \r
  65          */\r
  66         virtual bool readString(const char* key, std::string& value, time_t modifiedSince=0)=0;\r
  67 \r
  68         /**\r
  69          * Updates an existing "short" record in the storage service.\r
  70          * \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, or NULL to leave alone\r
  73          * @param expiration    a new expiration timestamp, or 0 to leave alone\r
  74          * @return true iff the record exists and was updated\r
  75          *    \r
  76          * @throws IOException  raised if errors occur in the update process \r
  77          */\r
  78         virtual bool updateString(const char* key, const char* value=NULL, time_t expiration=0)=0;\r
  79         \r
  80         /**\r
  81          * Deletes an existing "short" record from the storage service.\r
  82          * \r
  83          * @param key           null-terminated unique key of up to 255 bytes\r
  84          * @return true iff the record existed and was deleted\r
  85          *    \r
  86          * @throws IOException  raised if errors occur in the deletion process \r
  87          */\r
  88         virtual bool deleteString(const char* key)=0;\r
  89         \r
  90         /**\r
  91          * Creates a new "long" record in the storage service.\r
  92          * \r
  93          * @param key           null-terminated unique key of up to 255 bytes\r
  94          * @param value         null-terminated value of arbitrary length\r
  95          * @param expiration    an expiration timestamp, after which the record can be purged\r
  96          * \r
  97          * @throws IOException  raised if errors occur in the insertion process \r
  98          */\r
  99         virtual void createText(const char* key, const char* value, time_t expiration)=0;\r
 100         \r
 101         /**\r
 102          * Returns an existing "long" record from the storage service.\r
 103          * \r
 104          * @param key           null-terminated unique key of up to 255 bytes\r
 105          * @param value         location in which to return the record value\r
 106          * @param modifiedSince the record should not be returned if unmodified since this time,\r
 107          *  or 0 to always return\r
 108          * @return  true iff the record exists and was returned (based on the modifiedSince value)\r
 109          *    \r
 110          * @throws IOException  raised if errors occur in the read process \r
 111          */\r
 112         virtual bool readText(const char* key, std::string& value, time_t modifiedSince=0)=0;\r
 113 \r
 114         /**\r
 115          * Updates an existing "long" record in the storage service.\r
 116          * \r
 117          * @param key           null-terminated unique key of up to 255 bytes\r
 118          * @param value         null-terminated value of arbitrary length to store, or NULL to leave alone\r
 119          * @param expiration    a new expiration timestamp, or 0 to leave alone\r
 120          * @return true iff the record exists and was updated\r
 121          *    \r
 122          * @throws IOException  raised if errors occur in the update process \r
 123          */\r
 124         virtual bool updateText(const char* key, const char* value=NULL, time_t expiration=0)=0;\r
 125         \r
 126         /**\r
 127          * Deletes an existing "long" record from the storage service.\r
 128          * \r
 129          * @param key           null-terminated unique key of up to 255 bytes\r
 130          * @return true iff the record existed and was deleted\r
 131          *    \r
 132          * @throws IOException  raised if errors occur in the deletion process \r
 133          */\r
 134         virtual bool deleteText(const char* key)=0;\r
 135         \r
 136         /**\r
 137          * Manually trigger a cleanup of expired records.\r
 138          * The method <strong>MAY</strong> return without guaranteeing that\r
 139          * cleanup has already occurred.\r
 140          */\r
 141         virtual void reap()=0;\r
 142     };\r
 143 \r
 144     /**\r
 145      * Registers StorageService classes into the runtime.\r
 146      */\r
 147     void XMLTOOL_API registerStorageServices();\r
 148 \r
 149     /** StorageService based on in-memory caching. */\r
 150     #define MEMORY_STORAGE_SERVICE  "org.opensaml.xmlooling.MemoryStorageService"\r
 151 };\r
 152 \r
 153 #endif /* __xmltooling_storage_h__ */\r