1 /***
2 *
3 * Copyright 2004 Protique Ltd
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 **/
18
19 package org.activecluster;
20
21 import javax.jms.*;
22 import java.io.Serializable;
23 import java.util.Map;
24
25
26 /***
27 * Represents a logical connection to a cluster. From this object you can
28 * obtain the destination to send messages to, view the members of the cluster,
29 * watch cluster events (nodes joining, leaving, updating their state) as well
30 * as viewing each members state.
31 * <p/>
32 * You may also update the local node's state.
33 *
34 * @version $Revision: 1.1 $
35 */
36 public interface Cluster extends Service {
37
38 /***
39 * Returns the destination used to send a message to all members of the cluster
40 *
41 * @return the destination to send messages to all members of the cluster
42 */
43 public Topic getDestination();
44
45 /***
46 * A snapshot of the nodes in the cluster indexed by the Destination
47 */
48 public Map getNodes();
49
50 /***
51 * Adds a new listener to cluster events
52 *
53 * @param listener
54 */
55 public void addClusterListener(ClusterListener listener);
56
57 /***
58 * Removes a listener to cluster events
59 *
60 * @param listener
61 */
62 public void removeClusterListener(ClusterListener listener);
63
64 /***
65 * The local Node which allows you to mutate the state or subscribe to the
66 * nodes temporary queue for inbound messages direct to the Node
67 */
68 public LocalNode getLocalNode();
69
70
71
72
73
74 /***
75 * Sends a message to a destination, which could be to the entire group
76 * or could be a single Node's destination
77 *
78 * @param destination is either the group topic or a node's destination
79 * @param message the message to be sent
80 * @throws JMSException
81 */
82 public void send(Destination destination, Message message) throws JMSException;
83
84 /***
85 * Creates a consumer of all the messags sent to the given destination,
86 * including messages sent via the send() messages
87 *
88 * @param destination
89 * @return a newly created message consumer
90 * @throws JMSException
91 */
92 public MessageConsumer createConsumer(Destination destination) throws JMSException;
93
94 /***
95 * Creates a consumer of all message sent to the given destination,
96 * including messages sent via the send() message with an optional SQL 92 based selector to filter
97 * messages
98 *
99 * @param destination
100 * @param selector
101 * @return a newly created message consumer
102 * @throws JMSException
103 */
104 public MessageConsumer createConsumer(Destination destination, String selector) throws JMSException;
105
106 /***
107 * Creates a consumer of all message sent to the given destination,
108 * including messages sent via the send() message with an optional SQL 92 based selector to filter
109 * messages along with optionally ignoring local traffic - messages sent via the send()
110 * method on this object.
111 *
112 * @param destination the destination to consume from
113 * @param selector an optional SQL 92 filter of messages which could be null
114 * @param noLocal which if true messages sent via send() on this object will not be delivered to the consumer
115 * @return a newly created message consumer
116 * @throws JMSException
117 */
118 public MessageConsumer createConsumer(Destination destination, String selector, boolean noLocal) throws JMSException;
119
120
121
122
123
124 /***
125 * Creates a new message without a body
126 *
127 * @throws JMSException
128 */
129 public Message createMessage() throws JMSException;
130
131 /***
132 * Creates a new bytes message
133 *
134 * @throws JMSException
135 */
136 public BytesMessage createBytesMessage() throws JMSException;
137
138 /***
139 * Creates a new {@link MapMessage}
140 *
141 * @throws JMSException
142 */
143 public MapMessage createMapMessage() throws JMSException;
144
145 /***
146 * Creates a new {@link ObjectMessage}
147 *
148 * @throws JMSException
149 */
150 public ObjectMessage createObjectMessage() throws JMSException;
151
152 /***
153 * Creates a new {@link ObjectMessage}
154 *
155 * @param object
156 * @throws JMSException
157 */
158 public ObjectMessage createObjectMessage(Serializable object) throws JMSException;
159
160 /***
161 * Creates a new {@link StreamMessage}
162 *
163 * @throws JMSException
164 */
165 public StreamMessage createStreamMessage() throws JMSException;
166
167 /***
168 * Creates a new {@link TextMessage}
169 *
170 * @throws JMSException
171 */
172 public TextMessage createTextMessage() throws JMSException;
173
174 /***
175 * Creates a new {@link TextMessage}
176 *
177 * @param text
178 * @throws JMSException
179 */
180 public TextMessage createTextMessage(String text) throws JMSException;
181
182 /***
183 * wait until a the cardimality of the cluster is reaches the expected count. This method will return false if the
184 * cluster isn't started or stopped while waiting
185 *
186 * @param expectedCount the number of expected members of a cluster
187 * @param timeout timeout in milliseconds
188 * @return true if the cluster is fully connected
189 * @throws InterruptedException
190 */
191 boolean waitForClusterToComplete(int expectedCount, long timeout) throws InterruptedException;
192 }