2 * Copyright 2001-2006 Internet2
\r
4 * Licensed under the Apache License, Version 2.0 (the "License");
\r
5 * you may not use this file except in compliance with the License.
\r
6 * You may obtain a copy of the License at
\r
8 * http://www.apache.org/licenses/LICENSE-2.0
\r
10 * Unless required by applicable law or agreed to in writing, software
\r
11 * distributed under the License is distributed on an "AS IS" BASIS,
\r
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\r
13 * See the License for the specific language governing permissions and
\r
14 * limitations under the License.
\r
18 * @file xmltooling/util/StorageService.h
\r
20 * Generic data storage interface
\r
23 #ifndef __xmltooling_storage_h__
\r
24 #define __xmltooling_storage_h__
\r
26 #include <xmltooling/XMLObject.h>
\r
30 namespace xmltooling {
\r
33 * Generic data storage facility for use by services that require
\r
34 * some degree of persistence. Implementations will vary in how much
\r
35 * persistence they can supply.
\r
37 * <p>Storage is divided into "contexts" identified by a string label.
\r
38 * Keys need to be unique only within a given context, so multiple
\r
39 * components can share a single storage service safely as long as they
\r
40 * use different labels.
\r
42 class XMLTOOL_API StorageService
\r
44 MAKE_NONCOPYABLE(StorageService);
\r
46 virtual ~StorageService() {}
\r
49 * Creates a new "short" record in the storage service.
\r
51 * @param context a storage context label
\r
52 * @param key null-terminated unique key of up to 255 bytes
\r
53 * @param value null-terminated value of up to 255 bytes to store
\r
54 * @param expiration an expiration timestamp, after which the record can be purged
\r
56 * @throws IOException raised if errors occur in the insertion process
\r
58 virtual void createString(const char* context, const char* key, const char* value, time_t expiration)=0;
\r
61 * Returns an existing "short" record from the storage service.
\r
63 * @param context a storage context label
\r
64 * @param key null-terminated unique key of up to 255 bytes
\r
65 * @param value location in which to return the record value
\r
66 * @param modifiedSince the record should not be returned if unmodified since this time,
\r
67 * or 0 to always return
\r
68 * @return true iff the record exists and was returned (based on the modifiedSince value)
\r
70 * @throws IOException raised if errors occur in the read process
\r
72 virtual bool readString(const char* context, const char* key, std::string& value, time_t modifiedSince=0)=0;
\r
75 * Updates an existing "short" record in the storage service.
\r
77 * @param context a storage context label
\r
78 * @param key null-terminated unique key of up to 255 bytes
\r
79 * @param value null-terminated value of up to 255 bytes to store, or NULL to leave alone
\r
80 * @param expiration a new expiration timestamp, or 0 to leave alone
\r
81 * @return true iff the record exists and was updated
\r
83 * @throws IOException raised if errors occur in the update process
\r
85 virtual bool updateString(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;
\r
88 * Deletes an existing "short" record from the storage service.
\r
90 * @param context a storage context label
\r
91 * @param key null-terminated unique key of up to 255 bytes
\r
92 * @return true iff the record existed and was deleted
\r
94 * @throws IOException raised if errors occur in the deletion process
\r
96 virtual bool deleteString(const char* context, const char* key)=0;
\r
99 * Creates a new "long" record in the storage service.
\r
101 * @param context a storage context label
\r
102 * @param key null-terminated unique key of up to 255 bytes
\r
103 * @param value null-terminated value of arbitrary length
\r
104 * @param expiration an expiration timestamp, after which the record can be purged
\r
106 * @throws IOException raised if errors occur in the insertion process
\r
108 virtual void createText(const char* context, const char* key, const char* value, time_t expiration)=0;
\r
111 * Returns an existing "long" record from the storage service.
\r
113 * @param context a storage context label
\r
114 * @param key null-terminated unique key of up to 255 bytes
\r
115 * @param value location in which to return the record value
\r
116 * @param modifiedSince the record should not be returned if unmodified since this time,
\r
117 * or 0 to always return
\r
118 * @return true iff the record exists and was returned (based on the modifiedSince value)
\r
120 * @throws IOException raised if errors occur in the read process
\r
122 virtual bool readText(const char* context, const char* key, std::string& value, time_t modifiedSince=0)=0;
\r
125 * Updates an existing "long" record in the storage service.
\r
127 * @param context a storage context label
\r
128 * @param key null-terminated unique key of up to 255 bytes
\r
129 * @param value null-terminated value of arbitrary length to store, or NULL to leave alone
\r
130 * @param expiration a new expiration timestamp, or 0 to leave alone
\r
131 * @return true iff the record exists and was updated
\r
133 * @throws IOException raised if errors occur in the update process
\r
135 virtual bool updateText(const char* context, const char* key, const char* value=NULL, time_t expiration=0)=0;
\r
138 * Deletes an existing "long" record from the storage service.
\r
140 * @param context a storage context label
\r
141 * @param key null-terminated unique key of up to 255 bytes
\r
142 * @return true iff the record existed and was deleted
\r
144 * @throws IOException raised if errors occur in the deletion process
\r
146 virtual bool deleteText(const char* context, const char* key)=0;
\r
149 * Manually trigger a cleanup of expired records.
\r
150 * The method <strong>MAY</strong> return without guaranteeing that
\r
151 * cleanup has already occurred.
\r
153 * @param context a storage context label
\r
155 virtual void reap(const char* context)=0;
\r
158 * Forcibly removes all records in a given context along with any
\r
159 * associated resources devoted to maintaining the context.
\r
161 * @param context a storage context label
\r
163 virtual void deleteContext(const char* context)=0;
\r
166 StorageService() {}
\r
170 * Registers StorageService classes into the runtime.
\r
172 void XMLTOOL_API registerStorageServices();
\r
174 /** StorageService based on in-memory caching. */
\r
175 #define MEMORY_STORAGE_SERVICE "org.opensaml.xmlooling.MemoryStorageService"
\r
178 #endif /* __xmltooling_storage_h__ */
\r