2 * Copyright 2001-2007 Internet2
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file xmltooling/util/StorageService.h
20 * Generic data storage interface
23 #if !defined(__xmltooling_storage_h__) && !defined(XMLTOOLING_LITE)
24 #define __xmltooling_storage_h__
26 #include <xmltooling/XMLObject.h>
30 namespace xmltooling {
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.
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.
42 class XMLTOOL_API StorageService
44 MAKE_NONCOPYABLE(StorageService);
46 virtual ~StorageService() {}
49 * Creates a new "short" record in the storage service.
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 * @return true iff record was inserted, false iff a duplicate was found
57 * @throws IOException raised if fatal errors occur in the insertion process
59 virtual bool createString(const char* context, const char* key, const char* value, time_t expiration)=0;
62 * Returns an existing "short" record from the storage service.
64 * <p>The version parameter can be set for "If-Modified-Since" semantics.
66 * @param context a storage context label
67 * @param key null-terminated unique key of up to 255 bytes
68 * @param pvalue location in which to return the record value
69 * @param pexpiration location in which to return the expiration timestamp
70 * @param version if > 0, only copy back data if newer than supplied version
71 * @return the version of the record read back, or 0 if no record exists
73 * @throws IOException raised if errors occur in the read process
75 virtual int readString(
76 const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL, int version=0
80 * Updates an existing "short" record in the storage service.
82 * @param context a storage context label
83 * @param key null-terminated unique key of up to 255 bytes
84 * @param value null-terminated value of up to 255 bytes to store, or NULL to leave alone
85 * @param expiration a new expiration timestamp, or 0 to leave alone
86 * @param version if > 0, only update if the current version matches this value
87 * @return the version of the record after update, 0 if no record exists, or -1 if the version
88 * parameter is non-zero and does not match the current version before update (so the caller is out of sync)
90 * @throws IOException raised if errors occur in the update process
92 virtual int updateString(
93 const char* context, const char* key, const char* value=NULL, time_t expiration=0, int version=0
97 * Deletes an existing "short" record from the storage service.
99 * @param context a storage context label
100 * @param key null-terminated unique key of up to 255 bytes
101 * @return true iff the record existed and was deleted
103 * @throws IOException raised if errors occur in the deletion process
105 virtual bool deleteString(const char* context, const char* key)=0;
108 * Creates a new "long" record in the storage service.
110 * @param context a storage context label
111 * @param key null-terminated unique key of up to 255 bytes
112 * @param value null-terminated value of arbitrary length
113 * @param expiration an expiration timestamp, after which the record can be purged
114 * @return true iff record was inserted, false iff a duplicate was found
116 * @throws IOException raised if errors occur in the insertion process
118 virtual bool createText(const char* context, const char* key, const char* value, time_t expiration)=0;
121 * Returns an existing "long" record from the storage service.
123 * <p>The version parameter can be set for "If-Modified-Since" semantics.
125 * @param context a storage context label
126 * @param key null-terminated unique key of up to 255 bytes
127 * @param pvalue location in which to return the record value
128 * @param pexpiration location in which to return the expiration timestamp
129 * @param version if > 0, only copy back data if newer than supplied version
130 * @return the version of the record read back, or 0 if no record exists
132 * @throws IOException raised if errors occur in the read process
134 virtual int readText(
135 const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL, int version=0
139 * Updates an existing "long" record in the storage service.
141 * @param context a storage context label
142 * @param key null-terminated unique key of up to 255 bytes
143 * @param value null-terminated value of arbitrary length to store, or NULL to leave alone
144 * @param expiration a new expiration timestamp, or 0 to leave alone
145 * @param version if > 0, only update if the current version matches this value
146 * @return the version of the record after update, 0 if no record exists, or -1 if the version
147 * parameter is non-zero and does not match the current version before update (so the caller is out of sync)
149 * @throws IOException raised if errors occur in the update process
151 virtual int updateText(
152 const char* context, const char* key, const char* value=NULL, time_t expiration=0, int version=0
156 * Deletes an existing "long" record from the storage service.
158 * @param context a storage context label
159 * @param key null-terminated unique key of up to 255 bytes
160 * @return true iff the record existed and was deleted
162 * @throws IOException raised if errors occur in the deletion process
164 virtual bool deleteText(const char* context, const char* key)=0;
167 * Manually trigger a cleanup of expired records.
168 * The method <strong>MAY</strong> return without guaranteeing that
169 * cleanup has already occurred.
171 * @param context a storage context label
173 virtual void reap(const char* context)=0;
176 * Updates the expiration time of all records in the context.
178 * @param context a storage context label
179 * @param expiration a new expiration timestamp
181 virtual void updateContext(const char* context, time_t expiration)=0;
184 * Forcibly removes all records in a given context along with any
185 * associated resources devoted to maintaining the context.
187 * @param context a storage context label
189 virtual void deleteContext(const char* context)=0;
196 * Registers StorageService classes into the runtime.
198 void XMLTOOL_API registerStorageServices();
200 /** StorageService based on in-memory caching. */
201 #define MEMORY_STORAGE_SERVICE "Memory"
204 #endif /* __xmltooling_storage_h__ */