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      * <p>The allowable sizes for contexts, keys, and short values can vary
  47      * and be reported by the implementation to callers, but MUST be at least
  48      * 255 bytes.
  49      */
  50     class XMLTOOL_API StorageService
  51     {
  52         MAKE_NONCOPYABLE(StorageService);
  53     public:
  54         virtual ~StorageService();
  55
  56         class XMLTOOL_API Capabilities {
  57             MAKE_NONCOPYABLE(Capabilities);
  58             unsigned int m_contextSize, m_keySize, m_stringSize;
  59         public:
  60             /**
  61              * Constructor.
  62              *
  63              * @param contextSize   max size of context labels in characters
  64              * @param keysize       max size of keys in characters
  65              * @param stringSize    max size of string values in characters
  66              */
  67             Capabilities(unsigned int contextSize, unsigned int keySize, unsigned int stringSize);
  68             ~Capabilities();
  69
  70             /**
  71              * Returns max size of context labels in characters
  72              * @return  max size of context labels in characters
  73              */
  74             unsigned int getContextSize() const;
  75
  76             /**
  77              * Returns max size of keys in characters
  78              * @return  max size of keys in characters
  79              */
  80             unsigned int getKeySize() const;
  81
  82             /**
  83              * Returns max size of string values in characters
  84              * @return  max size of string values in characters
  85              */
  86             unsigned int getStringSize() const;
  87         };
  88
  89         /**
  90          * Returns the capabilities of the underlying service.
  91          * <p>If implementations support only the 255 character minimum, the default
  92          * implementation of this method will suffice.
  93          *
  94          * @return  a reference to an interface to access the service's capabilities
  95          */
  96         virtual const Capabilities& getCapabilities() const;
  97
  98         /**
  99          * Creates a new "short" record in the storage service.
 100          *
 101          * @param context       a storage context label
 102          * @param key           null-terminated unique key
 103          * @param value         null-terminated value
 104          * @param expiration    an expiration timestamp, after which the record can be purged
 105          * @return  true iff record was inserted, false iff a duplicate was found
 106          *
 107          * @throws IOException  raised if fatal errors occur in the insertion process
 108          */
 109         virtual bool createString(const char* context, const char* key, const char* value, time_t expiration)=0;
 110
 111         /**
 112          * Returns an existing "short" record from the storage service.
 113          *
 114          * <p>The version parameter can be set for "If-Modified-Since" semantics.
 115          *
 116          * @param context       a storage context label
 117          * @param key           null-terminated unique key
 118          * @param pvalue        location in which to return the record value
 119          * @param pexpiration   location in which to return the expiration timestamp
 120          * @param version       if > 0, only copy back data if newer than supplied version
 121          * @return  the version of the record read back, or 0 if no record exists
 122          *
 123          * @throws IOException  raised if errors occur in the read process
 124          */
 125         virtual int readString(
 126             const char* context, const char* key, std::string* pvalue=nullptr, time_t* pexpiration=nullptr, int version=0
 127             )=0;
 128
 129         /**
 130          * Updates an existing "short" record in the storage service.
 131          *
 132          * @param context       a storage context label
 133          * @param key           null-terminated unique key
 134          * @param value         null-terminated value to store, or nullptr to leave alone
 135          * @param expiration    a new expiration timestamp, or 0 to leave alone
 136          * @param version       if > 0, only update if the current version matches this value
 137          * @return the version of the record after update, 0 if no record exists, or -1 if the version
 138          *  parameter is non-zero and does not match the current version before update (so the caller is out of sync)
 139          *
 140          * @throws IOException  raised if errors occur in the update process
 141          */
 142         virtual int updateString(
 143             const char* context, const char* key, const char* value=nullptr, time_t expiration=0, int version=0
 144             )=0;
 145
 146         /**
 147          * Deletes an existing "short" record from the storage service.
 148          *
 149          * @param context       a storage context label
 150          * @param key           null-terminated unique key
 151          * @return true iff the record existed and was deleted
 152          *
 153          * @throws IOException  raised if errors occur in the deletion process
 154          */
 155         virtual bool deleteString(const char* context, const char* key)=0;
 156
 157         /**
 158          * Creates a new "long" record in the storage service.
 159          *
 160          * @param context       a storage context label
 161          * @param key           null-terminated unique key
 162          * @param value         null-terminated value of arbitrary length
 163          * @param expiration    an expiration timestamp, after which the record can be purged
 164          * @return  true iff record was inserted, false iff a duplicate was found
 165          *
 166          * @throws IOException  raised if errors occur in the insertion process
 167          */
 168         virtual bool createText(const char* context, const char* key, const char* value, time_t expiration)=0;
 169
 170         /**
 171          * Returns an existing "long" record from the storage service.
 172          *
 173          * <p>The version parameter can be set for "If-Modified-Since" semantics.
 174          *
 175          * @param context       a storage context label
 176          * @param key           null-terminated unique key
 177          * @param pvalue        location in which to return the record value
 178          * @param pexpiration   location in which to return the expiration timestamp
 179          * @param version       if > 0, only copy back data if newer than supplied version
 180          * @return  the version of the record read back, or 0 if no record exists
 181          *
 182          * @throws IOException  raised if errors occur in the read process
 183          */
 184         virtual int readText(
 185             const char* context, const char* key, std::string* pvalue=nullptr, time_t* pexpiration=nullptr, int version=0
 186             )=0;
 187
 188         /**
 189          * Updates an existing "long" record in the storage service.
 190          *
 191          * @param context       a storage context label
 192          * @param key           null-terminated unique key
 193          * @param value         null-terminated value of arbitrary length to store, or nullptr to leave alone
 194          * @param expiration    a new expiration timestamp, or 0 to leave alone
 195          * @param version       if > 0, only update if the current version matches this value
 196          * @return the version of the record after update, 0 if no record exists, or -1 if the version
 197          *  parameter is non-zero and does not match the current version before update (so the caller is out of sync)
 198          *
 199          * @throws IOException  raised if errors occur in the update process
 200          */
 201         virtual int updateText(
 202             const char* context, const char* key, const char* value=nullptr, time_t expiration=0, int version=0
 203             )=0;
 204
 205         /**
 206          * Deletes an existing "long" record from the storage service.
 207          *
 208          * @param context       a storage context label
 209          * @param key           null-terminated unique key
 210          * @return true iff the record existed and was deleted
 211          *
 212          * @throws IOException  raised if errors occur in the deletion process
 213          */
 214         virtual bool deleteText(const char* context, const char* key)=0;
 215
 216         /**
 217          * Manually trigger a cleanup of expired records.
 218          * The method <strong>MAY</strong> return without guaranteeing that
 219          * cleanup has already occurred.
 220          *
 221          * @param context       a storage context label
 222          */
 223         virtual void reap(const char* context)=0;
 224
 225         /**
 226          * Updates the expiration time of all records in the context.
 227          *
 228          * @param context       a storage context label
 229          * @param expiration    a new expiration timestamp
 230          */
 231         virtual void updateContext(const char* context, time_t expiration)=0;
 232
 233         /**
 234          * Forcibly removes all records in a given context along with any
 235          * associated resources devoted to maintaining the context.
 236          *
 237          * @param context       a storage context label
 238          */
 239         virtual void deleteContext(const char* context)=0;
 240
 241     protected:
 242         StorageService();
 243     };
 244
 245     /**
 246      * Registers StorageService classes into the runtime.
 247      */
 248     void XMLTOOL_API registerStorageServices();
 249
 250     /** StorageService based on in-memory caching. */
 251     #define MEMORY_STORAGE_SERVICE  "Memory"
 252 };
 253
 254 #endif /* __xmltooling_storage_h__ */