1 package org.exolab.jms.messagemgr;
2
3 import java.util.List;
4 import java.util.Map;
5 import javax.jms.InvalidDestinationException;
6 import javax.jms.JMSException;
7
8 import org.exolab.jms.client.JmsDestination;
9 import org.exolab.jms.client.JmsTopic;
10 import org.exolab.jms.gc.GarbageCollectable;
11
12
13 /***
14 * <code>DestinationManager</code> is responsible for creating and managing the
15 * lifecycle of {@link DestinationCache} objects. The destination manager is
16 * also responsible for managing messages that are received by the message
17 * manager, which do not have any registered {@link DestinationCache}.
18 *
19 * @author <a href="mailto:tma@netspace.net.au">Tim Anderson</a>
20 * @version $Revision: 1.4 $ $Date: 2005/11/12 10:58:40 $
21 */
22 public interface DestinationManager
23 extends MessageManagerEventListener, GarbageCollectable {
24
25 /***
26 * Returns the cache for the supplied destination.
27 * <p/>
28 * If the cache doesn't exist, it will be created, and any registered {@link
29 * DestinationEventListener}s will be notified.
30 *
31 * @param destination the destination of the cache to return
32 * @return the cache associated with <code>destination</code>
33 * @throws InvalidDestinationException if <code>destination</code> doesn't
34 * exist
35 * @throws JMSException if the cache can't be created
36 */
37 DestinationCache getDestinationCache(JmsDestination destination)
38 throws JMSException;
39
40 /***
41 * Returns a destination given its name.
42 *
43 * @param name the name of the destination
44 * @return the destination corresponding to <code>name</code> or
45 * <code>null</code> if none exists
46 */
47 JmsDestination getDestination(String name);
48
49 /***
50 * Create a destination.
51 * <p/>
52 * Any registered {@link DestinationEventListener}s will be notified.
53 *
54 * @param destination the destination to create
55 * @throws InvalidDestinationException if the destination already exists or
56 * is a wildcard destination
57 * @throws JMSException if the destination can't be created
58 */
59 void createDestination(JmsDestination destination) throws JMSException;
60
61 /***
62 * Remove a destination.
63 * <p/>
64 * All messages and durable consumers will be removed. Any registered {@link
65 * DestinationEventListener}s will be notified.
66 *
67 * @param destination the destination to remove
68 * @throws InvalidDestinationException if the destination is invalid.
69 * @throws JMSException if the destination can't be removed
70 */
71 void removeDestination(JmsDestination destination) throws JMSException;
72
73 /***
74 * Returns all destinations.
75 *
76 * @return a list of JmsDestination instances.
77 * @throws JMSException for any JMS error
78 */
79 List getDestinations() throws JMSException;
80
81 /***
82 * Returns a map of all destinations that match the specified topic.
83 * <p/>
84 * If the topic represents a wildcard then it may match none, one or more
85 * destinations.
86 *
87 * @param topic the topic
88 * @return a map of topics to DestinationCache instances
89 */
90 Map getTopicDestinationCaches(JmsTopic topic);
91
92 /***
93 * Register an event listener to be notified when destinations are created
94 * and destroyed.
95 *
96 * @param listener the listener to add
97 */
98 void addDestinationEventListener(DestinationEventListener listener);
99
100 /***
101 * Remove an event listener.
102 *
103 * @param listener the listener to remove
104 */
105 void removeDestinationEventListener(DestinationEventListener listener);
106
107 }