2 * Copyright 2001-2006 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 #ifndef __xmltooling_storage_h__
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
56 * @throws IOException raised if errors occur in the insertion process
58 virtual void createString(const char* context, const char* key, const char* value, time_t expiration)=0;
61 * Returns an existing "short" record from the storage service.
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
69 * @throws IOException raised if errors occur in the read process
71 virtual bool readString(const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL)=0;
74 * Updates an existing "short" record in the storage service.
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
82 * @throws IOException raised if errors occur in the update process
84 virtual bool updateString(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;
87 * Deletes an existing "short" record from the storage service.
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
93 * @throws IOException raised if errors occur in the deletion process
95 virtual bool deleteString(const char* context, const char* key)=0;
98 * Creates a new "long" record in the storage service.
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
105 * @throws IOException raised if errors occur in the insertion process
107 virtual void createText(const char* context, const char* key, const char* value, time_t expiration)=0;
110 * Returns an existing "long" record from the storage service.
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
118 * @throws IOException raised if errors occur in the read process
120 virtual bool readText(const char* context, const char* key, std::string* pvalue=NULL, time_t* pexpiration=NULL)=0;
123 * Updates an existing "long" record in the storage service.
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
131 * @throws IOException raised if errors occur in the update process
133 virtual bool updateText(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;
136 * Deletes an existing "long" record from the storage service.
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
142 * @throws IOException raised if errors occur in the deletion process
144 virtual bool deleteText(const char* context, const char* key)=0;
147 * Manually trigger a cleanup of expired records.
148 * The method <strong>MAY</strong> return without guaranteeing that
149 * cleanup has already occurred.
151 * @param context a storage context label
153 virtual void reap(const char* context)=0;
156 * Forcibly removes all records in a given context along with any
157 * associated resources devoted to maintaining the context.
159 * @param context a storage context label
161 virtual void deleteContext(const char* context)=0;
168 * Registers StorageService classes into the runtime.
170 void XMLTOOL_API registerStorageServices();
172 /** StorageService based on in-memory caching. */
173 #define MEMORY_STORAGE_SERVICE "org.opensaml.xmlooling.MemoryStorageService"
176 #endif /* __xmltooling_storage_h__ */