xmltooling/util/StorageService.h

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