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-2003 (C) Exoffice Technologies Inc. All Rights Reserved.
42 *
43 * $Id: PersistenceAdapter.java,v 1.39.2.1 2004/05/04 01:26:48 tanderson Exp $
44 *
45 * Date Author Changes
46 * $Date jimm Created
47 */
48
49 package org.exolab.jms.persistence;
50
51 import java.sql.Connection;
52 import java.util.Enumeration;
53 import java.util.HashMap;
54 import java.util.Vector;
55
56 import javax.jms.JMSException;
57
58 import org.exolab.jms.authentication.User;
59 import org.exolab.jms.client.JmsDestination;
60 import org.exolab.jms.config.DatabaseConfiguration;
61 import org.exolab.jms.message.MessageImpl;
62 import org.exolab.jms.messagemgr.PersistentMessageHandle;
63
64
65 /***
66 * This adapter is a wrapper class around the persistency mechanism.
67 * It isolates the client from the working specifics of the database, by
68 * providing a simple straight forward interface. Future changes to
69 * the database will only require changes to the adapter.
70 *
71 * @version $Revision: 1.39.2.1 $ $Date: 2004/05/04 01:26:48 $
72 * @author <a href="mailto:mourikis@exolab.org">Jim Mourikis</a>
73 * @see org.exolab.jms.persistence.ObjectAdapter
74 * @see org.exolab.jms.persistence.RDBMSAdapter
75 **/
76 public abstract class PersistenceAdapter {
77
78 /***
79 * Close the database if open.
80 *
81 */
82 public abstract void close();
83
84 /***
85 * Check to see if the root is created. If its not then create it
86 * and initialise it to 0.
87 * Return the value of this root id.
88 *
89 * @return long The id of the last batch.
90 * @throws PersistenceException
91 */
92 public abstract long getLastId(Connection connection)
93 throws PersistenceException;
94
95 /***
96 * Update the given id.
97 *
98 * @param connection - the connection to use
99 * @param id The id to set in the database.
100 * @throws PersistenceException
101 */
102 public abstract void updateIds(Connection connection, long id)
103 throws PersistenceException;
104
105 /***
106 * Add a new message to the database.
107 *
108 * @param connection - the connection to use
109 * @param MessageImpl the new message to add
110 * @throws PersistenceException
111 */
112 public abstract void addMessage(Connection connection,
113 MessageImpl message)
114 throws PersistenceException;
115
116 /***
117 * Update this message in the database
118 *
119 * @param connection - the connection to use
120 * @param MessageImpl the new message to update
121 * @throws PersistenceException
122 */
123 public abstract void updateMessage(Connection connection,
124 MessageImpl message)
125 throws PersistenceException;
126
127 /***
128 * Remove the message with the specified identity from the database
129 *
130 * @param connection - the connection to use
131 * @param name - the identity of the message to remove.
132 * @throws PersistenceException
133 */
134 public abstract void removeMessage(Connection connection,
135 String id)
136 throws PersistenceException;
137
138 /***
139 * Remove all expired messages and associated references from the
140 * database. It uses the current time to determine messages that
141 * have exipred.
142 *
143 * @param connection - the connection to use
144 * @throws PersistenceException
145 */
146 public abstract void removeExpiredMessages(Connection connection)
147 throws PersistenceException;
148
149 /***
150 * Remove all expired messages handles associated with this durable
151 * consumer.
152 *
153 * @param connection - the connection to use
154 * @param consumer - the durable consumer name
155 * @throws PersistenceException
156 */
157 public abstract void removeExpiredMessageHandles(Connection connection,
158 String consumer)
159 throws PersistenceException;
160
161 /***
162 * Retrieve a list of unexpired {@link PersistentMessageHandle} objects,
163 * for the specified destination.
164 *
165 * @param connection - the connection to use
166 * @param destination - the destination in question
167 * @return Vector - collection of unexpired message handles
168 * @throws PersistenceException
169 */
170 public abstract Vector getNonExpiredMessages(Connection connection,
171 JmsDestination destination)
172 throws PersistenceException;
173
174 /***
175 * Get a message from the persistence store.
176 *
177 * @param connection - the connection to use
178 * @param String The id of the message to search for
179 * @return MessageImpl The message if found otherwise null
180 * @throws PersistenceException
181 */
182 public abstract MessageImpl getMessage(Connection connection,
183 String id)
184 throws PersistenceException;
185
186 /***
187 * Get at least the next message given the specified persistent
188 * handle. The handle encodes all the information, including destination
189 * and timestamp, required to fetch that and successive messages. This
190 * will fault in more than one message for performance
191 *
192 * @param connection - the connection to use
193 * @param handle - the persistent handle to resolve
194 * @return Vector - a vector of MessageImpl
195 * @throws PersistenceException
196 */
197 public abstract Vector getMessages(Connection connection,
198 PersistentMessageHandle handle)
199 throws PersistenceException;
200
201 /***
202 * Return a list of unprocessed messages. These are messages that have
203 * been stored in the database but not processed.
204 *
205 * @param connection - the connection to use
206 * @return Vector - a collection of un processed messages
207 * @throws PersistenceException
208 */
209 public abstract Vector getUnprocessedMessages(Connection connection)
210 throws PersistenceException;
211
212 /***
213 * Add the specified persistent message handle.
214 *
215 * @param connection - the connection to use
216 * @param handle - the persistent handle to add
217 * @throws PersistenceException
218 */
219 public abstract void addMessageHandle(Connection connection,
220 PersistentMessageHandle handle)
221 throws PersistenceException;
222
223 /***
224 * Update the specified persistent message handle.
225 *
226 * @param connection - the connection to use
227 * @param handle - the persistent handle to update
228 * @throws PersistenceException
229 */
230 public abstract void updateMessageHandle(Connection connection,
231 PersistentMessageHandle handle)
232 throws PersistenceException;
233
234 /***
235 * Remove the specified persistent message handle.
236 *
237 * @param connection - the connection to use
238 * @param handle - the persistent handle to remove
239 * @throws PersistenceException
240 * @throws PersistenceException
241 */
242 public abstract void removeMessageHandle(Connection connection,
243 PersistentMessageHandle handle)
244 throws PersistenceException;
245
246 /***
247 * Get all the persistent message handles for the specified destination
248 * and consumer name.
249 * <p>
250 * The returned messages reference unacked or unsent messages
251 * <p>
252 * NEED A STRATEGY WHEN WE HAVE LOTS OF MESSAGE HANDLES
253 *
254 * @param connection - the connection to use
255 * @param destination - the destination to reference
256 * @param name - the consumer name
257 * @throws PersistenceException
258 */
259 public abstract Vector getMessageHandles(Connection connection,
260 JmsDestination destination, String name)
261 throws PersistenceException;
262
263 /***
264 * Add the specified durable consumer
265 *
266 * @param connection - the connection to use
267 * @param topic - the name of the topic
268 * @param name - the name of the consumer
269 * @throws PersistenceException
270 */
271 public abstract void addDurableConsumer(Connection connection,
272 String topic, String consumer)
273 throws PersistenceException;
274
275 /***
276 * Remove the durable consumer for the specified topic.
277 *
278 * @param connection - the connection to use
279 * @param consumer - the consumer name
280 * @throws PersistenceException
281 */
282 public abstract void removeDurableConsumer(Connection connection,
283 String consumer)
284 throws PersistenceException;
285
286 /***
287 * Check if the durable consumer exists
288 *
289 * @param connection - the connection to use
290 * @param name - durable consumer name
291 * @return boolean - true if it exists and false otherwise
292 * @throws PersistenceException
293 */
294 public abstract boolean durableConsumerExists(Connection connection,
295 String name)
296 throws PersistenceException;
297
298 /***
299 * Get an enumerated list of all durable consumers for the
300 * specified JmsTopic destination
301 *
302 * @param connection - the connection to use
303 * @param topic - the topic to query
304 * @return Vector - list of durable subscriber names
305 * @throws PersistenceException
306 */
307 public abstract Enumeration getDurableConsumers(Connection connection,
308 String topic)
309 throws PersistenceException;
310
311 /***
312 * Return a dictionary of all registered durable consumers. The
313 * dictionary is keyed on consumer name and maps to the underlying
314 * destination name. The destination name maybe a wildcard
315 *
316 * @param connection - the connection to use
317 * @return HashMap key=consumer name and value is destination
318 * @throws PersistenceException
319 */
320 public abstract HashMap getAllDurableConsumers(Connection connection)
321 throws PersistenceException;
322
323 /***
324 * Add a new destination to the database.
325 *
326 * @param connection - the connection to use
327 * @param name - the destination name
328 * @param queue - true if it pertains to a queue
329 * @throws PersistenceException
330 */
331 public abstract void addDestination(Connection connection,
332 String name, boolean queue)
333 throws PersistenceException;
334
335 /***
336 * Remove the destination with the specified name and all registered
337 * consumers from the database.
338 * Consumer registrations.
339 *
340 * @param connection - the connection to use
341 * @param destination - the name of the destination
342 * @throws PersistenceException
343 */
344 public abstract void removeDestination(Connection connection,
345 String destination)
346 throws PersistenceException;
347
348 /***
349 * Determine if a particular destination name exists
350 *
351 * @param connection - the connection to use
352 * @param name - the name to query
353 * @return boolean - true if it exists; false otherwise
354 * @throws PersistenceException
355 */
356 public abstract boolean checkDestination(Connection connection,
357 String name)
358 throws PersistenceException;
359
360 /***
361 * Get a list of all destinations stored in the database
362 *
363 * @param connection - the connection to use
364 * @return Enumeration - the list of destinations
365 * @throws PersistenceException
366 */
367 public abstract Enumeration getAllDestinations(Connection connection)
368 throws PersistenceException;
369
370 /***
371 * Get the number of unsent messages for a the specified queue
372 *
373 * @param connection - the connection to use
374 * @param name - the name of the queue
375 * @return int - the number of unsent or unacked messages
376 * @throws PersistenceException
377 */
378 public abstract int getQueueMessageCount(Connection connection,
379 String name)
380 throws PersistenceException;
381
382 /***
383 * Return the number of unsent message for the specified durable
384 * consumer.
385 *
386 * @param connection - the connection to use
387 * @param destination - the destination name
388 * @param name - the name of the durable subscriber
389 * @return int - the nmber of unsent or unacked messages
390 * @throws PersistenceException
391 */
392 public abstract int getDurableConsumerMessageCount(Connection connection,
393 String destination, String name)
394 throws PersistenceException;
395
396 /***
397 * Purge all processed messages from the database.
398 *
399 * @return int - the number of messages purged
400 * @deprecated no replacement
401 */
402 public abstract int purgeMessages();
403
404 /***
405 * Return a connection to this persistent data store.
406 *
407 * @return Connection - a connection to the persistent store or null
408 * @throws PersistenceException - if it cannot retrieve a connection
409 */
410 public abstract Connection getConnection() throws PersistenceException;
411
412
413 public abstract Enumeration getAllUsers(Connection connection)
414 throws PersistenceException;
415
416 public abstract void addUser(Connection connection, User user)
417 throws PersistenceException;
418
419 public abstract void removeUser(Connection connection,
420 User user)
421 throws PersistenceException;
422
423 public abstract void updateUser(Connection connection,
424 User user)
425 throws PersistenceException;
426
427 public abstract User getUser(Connection connection,
428 User user)
429 throws PersistenceException;
430
431 }
432
433
434
435