PersistenceAdapter


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 
427
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags