1 /***
2 * Redistribution and use of this software and associated documentation
3 * ("Software"), with or without modification, are permitted provided
4 * that the following conditions are met:
5 *
6 * 1. Redistributions of source code must retain copyright
7 * statements and notices. Redistributions must also contain a
8 * copy of this document.
9 *
10 * 2. Redistributions in binary form must reproduce the
11 * above copyright notice, this list of conditions and the
12 * following disclaimer in the documentation and/or other
13 * materials provided with the distribution.
14 *
15 * 3. The name "Exolab" must not be used to endorse or promote
16 * products derived from this Software without prior written
17 * permission of Exoffice Technologies. For written permission,
18 * please contact info@exolab.org.
19 *
20 * 4. Products derived from this Software may not be called "Exolab"
21 * nor may "Exolab" appear in their names without prior written
22 * permission of Exoffice Technologies. Exolab is a registered
23 * trademark of Exoffice Technologies.
24 *
25 * 5. Due credit should be given to the Exolab Project
26 * (http://www.exolab.org/).
27 *
28 * THIS SOFTWARE IS PROVIDED BY EXOFFICE TECHNOLOGIES AND CONTRIBUTORS
29 * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
30 * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
31 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
32 * EXOFFICE TECHNOLOGIES OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
33 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
34 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
35 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
36 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
37 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
38 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
39 * OF THE POSSIBILITY OF SUCH DAMAGE.
40 *
41 * Copyright 2000-2005 (C) Exoffice Technologies Inc. All Rights Reserved.
42 *
43 * $Id: PersistenceAdapter.java,v 1.2 2005/03/18 04:05:52 tanderson Exp $
44 */
45 package org.exolab.jms.persistence;
46
47 import java.sql.Connection;
48 import java.util.Enumeration;
49 import java.util.HashMap;
50 import java.util.Vector;
51
52 import org.exolab.jms.authentication.User;
53 import org.exolab.jms.client.JmsDestination;
54 import org.exolab.jms.message.MessageImpl;
55 import org.exolab.jms.messagemgr.MessageHandle;
56
57
58 /***
59 * This adapter is a wrapper class around the persistency mechanism.
60 * It isolates the client from the working specifics of the database, by
61 * providing a simple straight forward interface. Future changes to
62 * the database will only require changes to the adapter.
63 *
64 * @version $Revision: 1.2 $ $Date: 2005/03/18 04:05:52 $
65 * @author <a href="mailto:mourikis@exolab.org">Jim Mourikis</a>
66 * @see org.exolab.jms.persistence.RDBMSAdapter
67 */
68 public abstract class PersistenceAdapter {
69
70 /***
71 * Close the database if open.
72 *
73 */
74 public abstract void close();
75
76 /***
77 * Check to see if the root is created. If its not then create it
78 * and initialise it to 0.
79 * Return the value of this root id.
80 *
81 * @return long The id of the last batch.
82 * @throws PersistenceException
83 */
84 public abstract long getLastId(Connection connection)
85 throws PersistenceException;
86
87 /***
88 * Update the given id.
89 *
90 * @param connection - the connection to use
91 * @param id The id to set in the database.
92 * @throws PersistenceException
93 */
94 public abstract void updateIds(Connection connection, long id)
95 throws PersistenceException;
96
97 /***
98 * Add a new message to the database.
99 *
100 * @param connection the connection to use
101 * @param message the new message to add
102 * @throws PersistenceException
103 */
104 public abstract void addMessage(Connection connection,
105 MessageImpl message)
106 throws PersistenceException;
107
108 /***
109 * Update this message in the database
110 *
111 * @param connection the connection to use
112 * @param message the message to update
113 * @throws PersistenceException
114 */
115 public abstract void updateMessage(Connection connection,
116 MessageImpl message)
117 throws PersistenceException;
118
119 /***
120 * Remove the message with the specified identity from the database
121 *
122 * @param connection - the connection to use
123 * @param id the identity of the message to remove
124 * @throws PersistenceException
125 */
126 public abstract void removeMessage(Connection connection,
127 String id)
128 throws PersistenceException;
129
130 /***
131 * Remove all expired messages and associated references from the
132 * database. It uses the current time to determine messages that
133 * have exipred.
134 *
135 * @param connection - the connection to use
136 * @throws PersistenceException
137 */
138 public abstract void removeExpiredMessages(Connection connection)
139 throws PersistenceException;
140
141 /***
142 * Remove all expired messages handles associated with this durable
143 * consumer.
144 *
145 * @param connection - the connection to use
146 * @param consumer - the durable consumer name
147 * @throws PersistenceException
148 */
149 public abstract void removeExpiredMessageHandles(Connection connection,
150 String consumer)
151 throws PersistenceException;
152
153 /***
154 * Retrieve a list of unexpired {@link MessageHandle} objects,
155 * for the specified destination.
156 *
157 * @param connection - the connection to use
158 * @param destination - the destination in question
159 * @return Vector - collection of unexpired message handles
160 * @throws PersistenceException
161 */
162 public abstract Vector getNonExpiredMessages(Connection connection,
163 JmsDestination destination)
164 throws PersistenceException;
165
166 /***
167 * Get a message from the persistence store.
168 *
169 * @param connection - the connection to use
170 * @param id the id of the message to search for
171 * @return MessageImpl The message if found otherwise null
172 * @throws PersistenceException
173 */
174 public abstract MessageImpl getMessage(Connection connection,
175 String id)
176 throws PersistenceException;
177
178 /***
179 * Get at least the next message given the specified persistent
180 * handle. The handle encodes all the information, including destination
181 * and timestamp, required to fetch that and successive messages. This
182 * will fault in more than one message for performance
183 *
184 * @param connection - the connection to use
185 * @param handle - the persistent handle to resolve
186 * @return Vector - a vector of MessageImpl
187 * @throws PersistenceException
188 */
189 public abstract Vector getMessages(Connection connection,
190 MessageHandle handle)
191 throws PersistenceException;
192
193 /***
194 * Return a list of unprocessed messages. These are messages that have
195 * been stored in the database but not processed.
196 *
197 * @param connection - the connection to use
198 * @return Vector - a collection of un processed messages
199 * @throws PersistenceException
200 */
201 public abstract Vector getUnprocessedMessages(Connection connection)
202 throws PersistenceException;
203
204 /***
205 * Add the specified persistent message handle.
206 *
207 * @param connection - the connection to use
208 * @param handle - the persistent handle to add
209 * @throws PersistenceException
210 */
211 public abstract void addMessageHandle(Connection connection,
212 MessageHandle handle)
213 throws PersistenceException;
214
215 /***
216 * Update the specified persistent message handle.
217 *
218 * @param connection - the connection to use
219 * @param handle - the persistent handle to update
220 * @throws PersistenceException
221 */
222 public abstract void updateMessageHandle(Connection connection,
223 MessageHandle handle)
224 throws PersistenceException;
225
226 /***
227 * Remove the specified persistent message handle.
228 *
229 * @param connection - the connection to use
230 * @param handle - the persistent handle to remove
231 * @throws PersistenceException
232 * @throws PersistenceException
233 */
234 public abstract void removeMessageHandle(Connection connection,
235 MessageHandle handle)
236 throws PersistenceException;
237
238 /***
239 * Get all the persistent message handles for the specified destination
240 * and consumer name.
241 * <p>
242 * The returned messages reference unacked or unsent messages
243 * <p>
244 * NEED A STRATEGY WHEN WE HAVE LOTS OF MESSAGE HANDLES
245 *
246 * @param connection - the connection to use
247 * @param destination - the destination to reference
248 * @param name - the consumer name
249 * @throws PersistenceException
250 */
251 public abstract Vector getMessageHandles(Connection connection,
252 JmsDestination destination, String name)
253 throws PersistenceException;
254
255 /***
256 * Add the specified durable consumer
257 *
258 * @param connection - the connection to use
259 * @param topic - the name of the topic
260 * @param consumer the name of the consumer
261 * @throws PersistenceException
262 */
263 public abstract void addDurableConsumer(Connection connection,
264 String topic, String consumer)
265 throws PersistenceException;
266
267 /***
268 * Remove the durable consumer for the specified topic.
269 *
270 * @param connection - the connection to use
271 * @param consumer - the consumer name
272 * @throws PersistenceException
273 */
274 public abstract void removeDurableConsumer(Connection connection,
275 String consumer)
276 throws PersistenceException;
277
278 /***
279 * Check if the durable consumer exists
280 *
281 * @param connection - the connection to use
282 * @param name - durable consumer name
283 * @return boolean - true if it exists and false otherwise
284 * @throws PersistenceException
285 */
286 public abstract boolean durableConsumerExists(Connection connection,
287 String name)
288 throws PersistenceException;
289
290 /***
291 * Get an enumerated list of all durable consumers for the
292 * specified JmsTopic destination
293 *
294 * @param connection - the connection to use
295 * @param topic - the topic to query
296 * @return Vector - list of durable subscriber names
297 * @throws PersistenceException
298 */
299 public abstract Enumeration getDurableConsumers(Connection connection,
300 String topic)
301 throws PersistenceException;
302
303 /***
304 * Return a dictionary of all registered durable consumers. The
305 * dictionary is keyed on consumer name and maps to the underlying
306 * destination name. The destination name maybe a wildcard
307 *
308 * @param connection - the connection to use
309 * @return HashMap key=consumer name and value is destination
310 * @throws PersistenceException
311 */
312 public abstract HashMap getAllDurableConsumers(Connection connection)
313 throws PersistenceException;
314
315 /***
316 * Add a new destination to the database.
317 *
318 * @param connection - the connection to use
319 * @param name - the destination name
320 * @param queue - true if it pertains to a queue
321 * @throws PersistenceException
322 */
323 public abstract void addDestination(Connection connection,
324 String name, boolean queue)
325 throws PersistenceException;
326
327 /***
328 * Remove the destination with the specified name and all registered
329 * consumers from the database.
330 * Consumer registrations.
331 *
332 * @param connection - the connection to use
333 * @param destination - the name of the destination
334 * @throws PersistenceException
335 */
336 public abstract void removeDestination(Connection connection,
337 String destination)
338 throws PersistenceException;
339
340 /***
341 * Determine if a particular destination name exists
342 *
343 * @param connection - the connection to use
344 * @param name - the name to query
345 * @return boolean - true if it exists; false otherwise
346 * @throws PersistenceException
347 */
348 public abstract boolean checkDestination(Connection connection,
349 String name)
350 throws PersistenceException;
351
352 /***
353 * Get a list of all destinations stored in the database
354 *
355 * @param connection - the connection to use
356 * @return Enumeration - the list of destinations
357 * @throws PersistenceException
358 */
359 public abstract Enumeration getAllDestinations(Connection connection)
360 throws PersistenceException;
361
362 /***
363 * Get the number of unsent messages for a the specified queue
364 *
365 * @param connection - the connection to use
366 * @param name - the name of the queue
367 * @return int - the number of unsent or unacked messages
368 * @throws PersistenceException
369 */
370 public abstract int getQueueMessageCount(Connection connection,
371 String name)
372 throws PersistenceException;
373
374 /***
375 * Return the number of unsent message for the specified durable
376 * consumer.
377 *
378 * @param connection - the connection to use
379 * @param destination - the destination name
380 * @param name - the name of the durable subscriber
381 * @return int - the nmber of unsent or unacked messages
382 * @throws PersistenceException
383 */
384 public abstract int getDurableConsumerMessageCount(Connection connection,
385 String destination, String name)
386 throws PersistenceException;
387
388 /***
389 * Purge all processed messages from the database.
390 *
391 * @return int - the number of messages purged
392 */
393 public abstract int purgeMessages();
394
395 /***
396 * Return a connection to this persistent data store.
397 *
398 * @return Connection - a connection to the persistent store or null
399 * @throws PersistenceException - if it cannot retrieve a connection
400 */
401 public abstract Connection getConnection() throws PersistenceException;
402
403
404 public abstract Enumeration getAllUsers(Connection connection)
405 throws PersistenceException;
406
407 public abstract void addUser(Connection connection, User user)
408 throws PersistenceException;
409
410 public abstract void removeUser(Connection connection,
411 User user)
412 throws PersistenceException;
413
414 public abstract void updateUser(Connection connection,
415 User user)
416 throws PersistenceException;
417
418 public abstract User getUser(Connection connection,
419 User user)
420 throws PersistenceException;
421
422 }
423
424
425
426