xmltooling/util/StorageService.h

   1 /*
   2  *  Copyright 2001-2010 Internet2
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 /**
  18  * @file xmltooling/util/StorageService.h
  19  *
  20  * Generic data storage interface.
  21  */
  22
  23 #if !defined(__xmltooling_storage_h__) && !defined(XMLTOOLING_LITE)
  24 #define __xmltooling_storage_h__
  25
  26 #include <xmltooling/base.h>
  27
  28 #include <ctime>
  29
  30 namespace xmltooling {
  31
  32     /**
  33      * Generic data storage facility for use by services that require
  34      * some degree of persistence. Implementations will vary in how much
  35      * persistence they can supply.
  36      *
  37      * <p>Storage is divided into "contexts" identified by a string label.
  38      * Keys need to be unique only within a given context, so multiple
  39      * components can share a single storage service safely as long as they
  40      * use different labels.
  41      */
  42     class XMLTOOL_API StorageService
  43     {
  44         MAKE_NONCOPYABLE(StorageService);
  45     public:
  46         virtual ~StorageService();
  47
  48         /**
  49          * Creates a new "short" record in the storage service.
  50          *
  51          * @param context       a storage context label
  52          * @param key           null-terminated unique key of up to 255 bytes
  53          * @param value         null-terminated value of up to 255 bytes to store
  54          * @param expiration    an expiration timestamp, after which the record can be purged
  55          * @return  true iff record was inserted, false iff a duplicate was found
  56          *
  57          * @throws IOException  raised if fatal errors occur in the insertion process
  58          */
  59         virtual bool createString(const char* context, const char* key, const char* value, time_t expiration)=0;
  60
  61         /**
  62          * Returns an existing "short" record from the storage service.
  63          *
  64          * <p>The version parameter can be set for "If-Modified-Since" semantics.
  65          *
  66          * @param context       a storage context label
  67          * @param key           null-terminated unique key of up to 255 bytes
  68          * @param pvalue        location in which to return the record value
  69          * @param pexpiration   location in which to return the expiration timestamp
  70          * @param version       if > 0, only copy back data if newer than supplied version
  71          * @return  the version of the record read back, or 0 if no record exists
  72          *
  73          * @throws IOException  raised if errors occur in the read process
  74          */
  75         virtual int readString(
  76             const char* context, const char* key, std::string* pvalue=nullptr, time_t* pexpiration=nullptr, int version=0
  77             )=0;
  78
  79         /**
  80          * Updates an existing "short" record in the storage service.
  81          *
  82          * @param context       a storage context label
  83          * @param key           null-terminated unique key of up to 255 bytes
  84          * @param value         null-terminated value of up to 255 bytes to store, or nullptr to leave alone
  85          * @param expiration    a new expiration timestamp, or 0 to leave alone
  86          * @param version       if > 0, only update if the current version matches this value
  87          * @return the version of the record after update, 0 if no record exists, or -1 if the version
  88          *  parameter is non-zero and does not match the current version before update (so the caller is out of sync)
  89          *
  90          * @throws IOException  raised if errors occur in the update process
  91          */
  92         virtual int updateString(
  93             const char* context, const char* key, const char* value=nullptr, time_t expiration=0, int version=0
  94             )=0;
  95
  96         /**
  97          * Deletes an existing "short" record from the storage service.
  98          *
  99          * @param context       a storage context label
 100          * @param key           null-terminated unique key of up to 255 bytes
 101          * @return true iff the record existed and was deleted
 102          *
 103          * @throws IOException  raised if errors occur in the deletion process
 104          */
 105         virtual bool deleteString(const char* context, const char* key)=0;
 106
 107         /**
 108          * Creates a new "long" record in the storage service.
 109          *
 110          * @param context       a storage context label
 111          * @param key           null-terminated unique key of up to 255 bytes
 112          * @param value         null-terminated value of arbitrary length
 113          * @param expiration    an expiration timestamp, after which the record can be purged
 114          * @return  true iff record was inserted, false iff a duplicate was found
 115          *
 116          * @throws IOException  raised if errors occur in the insertion process
 117          */
 118         virtual bool createText(const char* context, const char* key, const char* value, time_t expiration)=0;
 119
 120         /**
 121          * Returns an existing "long" record from the storage service.
 122          *
 123          * <p>The version parameter can be set for "If-Modified-Since" semantics.
 124          *
 125          * @param context       a storage context label
 126          * @param key           null-terminated unique key of up to 255 bytes
 127          * @param pvalue        location in which to return the record value
 128          * @param pexpiration   location in which to return the expiration timestamp
 129          * @param version       if > 0, only copy back data if newer than supplied version
 130          * @return  the version of the record read back, or 0 if no record exists
 131          *
 132          * @throws IOException  raised if errors occur in the read process
 133          */
 134         virtual int readText(
 135             const char* context, const char* key, std::string* pvalue=nullptr, time_t* pexpiration=nullptr, int version=0
 136             )=0;
 137
 138         /**
 139          * Updates an existing "long" record in the storage service.
 140          *
 141          * @param context       a storage context label
 142          * @param key           null-terminated unique key of up to 255 bytes
 143          * @param value         null-terminated value of arbitrary length to store, or nullptr to leave alone
 144          * @param expiration    a new expiration timestamp, or 0 to leave alone
 145          * @param version       if > 0, only update if the current version matches this value
 146          * @return the version of the record after update, 0 if no record exists, or -1 if the version
 147          *  parameter is non-zero and does not match the current version before update (so the caller is out of sync)
 148          *
 149          * @throws IOException  raised if errors occur in the update process
 150          */
 151         virtual int updateText(
 152             const char* context, const char* key, const char* value=nullptr, time_t expiration=0, int version=0
 153             )=0;
 154
 155         /**
 156          * Deletes an existing "long" record from the storage service.
 157          *
 158          * @param context       a storage context label
 159          * @param key           null-terminated unique key of up to 255 bytes
 160          * @return true iff the record existed and was deleted
 161          *
 162          * @throws IOException  raised if errors occur in the deletion process
 163          */
 164         virtual bool deleteText(const char* context, const char* key)=0;
 165
 166         /**
 167          * Manually trigger a cleanup of expired records.
 168          * The method <strong>MAY</strong> return without guaranteeing that
 169          * cleanup has already occurred.
 170          *
 171          * @param context       a storage context label
 172          */
 173         virtual void reap(const char* context)=0;
 174
 175         /**
 176          * Updates the expiration time of all records in the context.
 177          *
 178          * @param context       a storage context label
 179          * @param expiration    a new expiration timestamp
 180          */
 181         virtual void updateContext(const char* context, time_t expiration)=0;
 182
 183         /**
 184          * Forcibly removes all records in a given context along with any
 185          * associated resources devoted to maintaining the context.
 186          *
 187          * @param context       a storage context label
 188          */
 189         virtual void deleteContext(const char* context)=0;
 190
 191     protected:
 192         StorageService();
 193     };
 194
 195     /**
 196      * Registers StorageService classes into the runtime.
 197      */
 198     void XMLTOOL_API registerStorageServices();
 199
 200     /** StorageService based on in-memory caching. */
 201     #define MEMORY_STORAGE_SERVICE  "Memory"
 202 };
 203
 204 #endif /* __xmltooling_storage_h__ */