xmltooling/util/StorageService.h

   1 /*
   2  *  Copyright 2001-2007 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 #ifndef __xmltooling_storage_h__
  24 #define __xmltooling_storage_h__
  25
  26 #include <xmltooling/XMLObject.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          *
  56          * @throws IOException  raised if errors occur in the insertion process
  57          */
  58         virtual void createString(const char* context, const char* key, const char* value, time_t expiration)=0;
  59
  60         /**
  61          * Returns an existing "short" record from the storage service.
  62          *
  63          * <p>The version parameter can be set for "If-Modified-Since" semantics.
  64          *
  65          * @param context       a storage context label
  66          * @param key           null-terminated unique key of up to 255 bytes
  67          * @param pvalue        location in which to return the record value
  68          * @param pexpiration   location in which to return the expiration timestamp
  69          * @param version       if > 0, only copy back data if newer than supplied version
  70          * @return  the version of the record read back, or 0 if no record exists
  71          *
  72          * @throws IOException  raised if errors occur in the read process
  73          */
  74         virtual int readString(
  75             const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL, int version=0
  76             )=0;
  77
  78         /**
  79          * Updates an existing "short" record in the storage service.
  80          *
  81          * @param context       a storage context label
  82          * @param key           null-terminated unique key of up to 255 bytes
  83          * @param value         null-terminated value of up to 255 bytes to store, or NULL to leave alone
  84          * @param expiration    a new expiration timestamp, or 0 to leave alone
  85          * @param version       if > 0, only update if the current version matches this value
  86          * @return the version of the record after update, 0 if no record exists, or -1 if the version
  87          *  parameter is non-zero and does not match the current version before update (so the caller is out of sync)
  88          *
  89          * @throws IOException  raised if errors occur in the update process
  90          */
  91         virtual int updateString(
  92             const char* context, const char* key, const char* value=NULL, time_t expiration=0, int version=0
  93             )=0;
  94
  95         /**
  96          * Deletes an existing "short" record from the storage service.
  97          *
  98          * @param context       a storage context label
  99          * @param key           null-terminated unique key of up to 255 bytes
 100          * @return true iff the record existed and was deleted
 101          *
 102          * @throws IOException  raised if errors occur in the deletion process
 103          */
 104         virtual bool deleteString(const char* context, const char* key)=0;
 105
 106         /**
 107          * Creates a new "long" record in the storage service.
 108          *
 109          * @param context       a storage context label
 110          * @param key           null-terminated unique key of up to 255 bytes
 111          * @param value         null-terminated value of arbitrary length
 112          * @param expiration    an expiration timestamp, after which the record can be purged
 113          *
 114          * @throws IOException  raised if errors occur in the insertion process
 115          */
 116         virtual void createText(const char* context, const char* key, const char* value, time_t expiration)=0;
 117
 118         /**
 119          * Returns an existing "long" record from the storage service.
 120          *
 121          * <p>The version parameter can be set for "If-Modified-Since" semantics.
 122          *
 123          * @param context       a storage context label
 124          * @param key           null-terminated unique key of up to 255 bytes
 125          * @param pvalue        location in which to return the record value
 126          * @param pexpiration   location in which to return the expiration timestamp
 127          * @param version       if > 0, only copy back data if newer than supplied version
 128          * @return  the version of the record read back, or 0 if no record exists
 129          *
 130          * @throws IOException  raised if errors occur in the read process
 131          */
 132         virtual int readText(
 133             const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL, int version=0
 134             )=0;
 135
 136         /**
 137          * Updates an existing "long" record in the storage service.
 138          *
 139          * @param context       a storage context label
 140          * @param key           null-terminated unique key of up to 255 bytes
 141          * @param value         null-terminated value of arbitrary length to store, or NULL to leave alone
 142          * @param expiration    a new expiration timestamp, or 0 to leave alone
 143          * @param version       if > 0, only update if the current version matches this value
 144          * @return the version of the record after update, 0 if no record exists, or -1 if the version
 145          *  parameter is non-zero and does not match the current version before update (so the caller is out of sync)
 146          *
 147          * @throws IOException  raised if errors occur in the update process
 148          */
 149         virtual int updateText(
 150             const char* context, const char* key, const char* value=NULL, time_t expiration=0, int version=0
 151             )=0;
 152
 153         /**
 154          * Deletes an existing "long" record from the storage service.
 155          *
 156          * @param context       a storage context label
 157          * @param key           null-terminated unique key of up to 255 bytes
 158          * @return true iff the record existed and was deleted
 159          *
 160          * @throws IOException  raised if errors occur in the deletion process
 161          */
 162         virtual bool deleteText(const char* context, const char* key)=0;
 163
 164         /**
 165          * Manually trigger a cleanup of expired records.
 166          * The method <strong>MAY</strong> return without guaranteeing that
 167          * cleanup has already occurred.
 168          *
 169          * @param context       a storage context label
 170          */
 171         virtual void reap(const char* context)=0;
 172
 173         /**
 174          * Forcibly removes all records in a given context along with any
 175          * associated resources devoted to maintaining the context.
 176          *
 177          * @param context       a storage context label
 178          */
 179         virtual void deleteContext(const char* context)=0;
 180
 181     protected:
 182         StorageService() {}
 183     };
 184
 185     /**
 186      * Registers StorageService classes into the runtime.
 187      */
 188     void XMLTOOL_API registerStorageServices();
 189
 190     /** StorageService based on in-memory caching. */
 191     #define MEMORY_STORAGE_SERVICE  "org.opensaml.xmlooling.MemoryStorageService"
 192 };
 193
 194 #endif /* __xmltooling_storage_h__ */