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.
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 * @file xmltooling/util/StorageService.h
24 * Generic data storage interface.
27 #if !defined(__xmltooling_storage_h__) && !defined(XMLTOOLING_LITE)
28 #define __xmltooling_storage_h__
30 #include <xmltooling/base.h>
34 namespace xmltooling {
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.
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.
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
50 class XMLTOOL_API StorageService
52 MAKE_NONCOPYABLE(StorageService);
54 virtual ~StorageService();
56 class XMLTOOL_API Capabilities {
57 MAKE_NONCOPYABLE(Capabilities);
58 unsigned int m_contextSize, m_keySize, m_stringSize;
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
67 Capabilities(unsigned int contextSize, unsigned int keySize, unsigned int stringSize);
71 * Returns max size of context labels in characters
72 * @return max size of context labels in characters
74 unsigned int getContextSize() const;
77 * Returns max size of keys in characters
78 * @return max size of keys in characters
80 unsigned int getKeySize() const;
83 * Returns max size of string values in characters
84 * @return max size of string values in characters
86 unsigned int getStringSize() const;
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.
94 * @return a reference to an interface to access the service's capabilities
96 virtual const Capabilities& getCapabilities() const;
99 * Creates a new "short" record in the storage service.
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
107 * @throws IOException raised if fatal errors occur in the insertion process
109 virtual bool createString(const char* context, const char* key, const char* value, time_t expiration)=0;
112 * Returns an existing "short" record from the storage service.
114 * <p>The version parameter can be set for "If-Modified-Since" semantics.
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
123 * @throws IOException raised if errors occur in the read process
125 virtual int readString(
126 const char* context, const char* key, std::string* pvalue=nullptr, time_t* pexpiration=nullptr, int version=0
130 * Updates an existing "short" record in the storage service.
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)
140 * @throws IOException raised if errors occur in the update process
142 virtual int updateString(
143 const char* context, const char* key, const char* value=nullptr, time_t expiration=0, int version=0
147 * Deletes an existing "short" record from the storage service.
149 * @param context a storage context label
150 * @param key null-terminated unique key
151 * @return true iff the record existed and was deleted
153 * @throws IOException raised if errors occur in the deletion process
155 virtual bool deleteString(const char* context, const char* key)=0;
158 * Creates a new "long" record in the storage service.
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
166 * @throws IOException raised if errors occur in the insertion process
168 virtual bool createText(const char* context, const char* key, const char* value, time_t expiration)=0;
171 * Returns an existing "long" record from the storage service.
173 * <p>The version parameter can be set for "If-Modified-Since" semantics.
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
182 * @throws IOException raised if errors occur in the read process
184 virtual int readText(
185 const char* context, const char* key, std::string* pvalue=nullptr, time_t* pexpiration=nullptr, int version=0
189 * Updates an existing "long" record in the storage service.
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)
199 * @throws IOException raised if errors occur in the update process
201 virtual int updateText(
202 const char* context, const char* key, const char* value=nullptr, time_t expiration=0, int version=0
206 * Deletes an existing "long" record from the storage service.
208 * @param context a storage context label
209 * @param key null-terminated unique key
210 * @return true iff the record existed and was deleted
212 * @throws IOException raised if errors occur in the deletion process
214 virtual bool deleteText(const char* context, const char* key)=0;
217 * Manually trigger a cleanup of expired records.
218 * The method <strong>MAY</strong> return without guaranteeing that
219 * cleanup has already occurred.
221 * @param context a storage context label
223 virtual void reap(const char* context)=0;
226 * Updates the expiration time of all records in the context.
228 * @param context a storage context label
229 * @param expiration a new expiration timestamp
231 virtual void updateContext(const char* context, time_t expiration)=0;
234 * Forcibly removes all records in a given context along with any
235 * associated resources devoted to maintaining the context.
237 * @param context a storage context label
239 virtual void deleteContext(const char* context)=0;
246 * Registers StorageService classes into the runtime.
248 void XMLTOOL_API registerStorageServices();
250 /** StorageService based on in-memory caching. */
251 #define MEMORY_STORAGE_SERVICE "Memory"
254 #endif /* __xmltooling_storage_h__ */