xmltooling/util/StorageService.h

   1 /*
   2  *  Copyright 2001-2006 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          * @param context       a storage context label
  64          * @param key           null-terminated unique key of up to 255 bytes
  65          * @param pvalue        location in which to return the record value
  66          * @param pexpiration   location in which to return the expiration timestamp
  67          * @return  true iff a valid record exists and was returned
  68          *
  69          * @throws IOException  raised if errors occur in the read process
  70          */
  71         virtual bool readString(const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL)=0;
  72
  73         /**
  74          * Updates an existing "short" record in the storage service.
  75          *
  76          * @param context       a storage context label
  77          * @param key           null-terminated unique key of up to 255 bytes
  78          * @param value         null-terminated value of up to 255 bytes to store, or NULL to leave alone
  79          * @param expiration    a new expiration timestamp, or 0 to leave alone
  80          * @return true iff the record exists and was updated
  81          *
  82          * @throws IOException  raised if errors occur in the update process
  83          */
  84         virtual bool updateString(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;
  85
  86         /**
  87          * Deletes an existing "short" record from the storage service.
  88          *
  89          * @param context       a storage context label
  90          * @param key           null-terminated unique key of up to 255 bytes
  91          * @return true iff the record existed and was deleted
  92          *
  93          * @throws IOException  raised if errors occur in the deletion process
  94          */
  95         virtual bool deleteString(const char* context, const char* key)=0;
  96
  97         /**
  98          * Creates a new "long" record in the storage service.
  99          *
 100          * @param context       a storage context label
 101          * @param key           null-terminated unique key of up to 255 bytes
 102          * @param value         null-terminated value of arbitrary length
 103          * @param expiration    an expiration timestamp, after which the record can be purged
 104          *
 105          * @throws IOException  raised if errors occur in the insertion process
 106          */
 107         virtual void createText(const char* context, const char* key, const char* value, time_t expiration)=0;
 108
 109         /**
 110          * Returns an existing "long" record from the storage service.
 111          *
 112          * @param context       a storage context label
 113          * @param key           null-terminated unique key of up to 255 bytes
 114          * @param pvalue        location in which to return the record value
 115          * @param pexpiration   location in which to return the expiration timestamp
 116          * @return  true iff a valid record exists and was returned
 117          *
 118          * @throws IOException  raised if errors occur in the read process
 119          */
 120         virtual bool readText(const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL)=0;
 121
 122         /**
 123          * Updates an existing "long" record in the storage service.
 124          *
 125          * @param context       a storage context label
 126          * @param key           null-terminated unique key of up to 255 bytes
 127          * @param value         null-terminated value of arbitrary length to store, or NULL to leave alone
 128          * @param expiration    a new expiration timestamp, or 0 to leave alone
 129          * @return true iff the record exists and was updated
 130          *
 131          * @throws IOException  raised if errors occur in the update process
 132          */
 133         virtual bool updateText(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;
 134
 135         /**
 136          * Deletes an existing "long" record from the storage service.
 137          *
 138          * @param context       a storage context label
 139          * @param key           null-terminated unique key of up to 255 bytes
 140          * @return true iff the record existed and was deleted
 141          *
 142          * @throws IOException  raised if errors occur in the deletion process
 143          */
 144         virtual bool deleteText(const char* context, const char* key)=0;
 145
 146         /**
 147          * Manually trigger a cleanup of expired records.
 148          * The method <strong>MAY</strong> return without guaranteeing that
 149          * cleanup has already occurred.
 150          *
 151          * @param context       a storage context label
 152          */
 153         virtual void reap(const char* context)=0;
 154
 155         /**
 156          * Forcibly removes all records in a given context along with any
 157          * associated resources devoted to maintaining the context.
 158          *
 159          * @param context       a storage context label
 160          */
 161         virtual void deleteContext(const char* context)=0;
 162
 163     protected:
 164         StorageService() {}
 165     };
 166
 167     /**
 168      * Registers StorageService classes into the runtime.
 169      */
 170     void XMLTOOL_API registerStorageServices();
 171
 172     /** StorageService based on in-memory caching. */
 173     #define MEMORY_STORAGE_SERVICE  "org.opensaml.xmlooling.MemoryStorageService"
 174 };
 175
 176 #endif /* __xmltooling_storage_h__ */