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.codehaus.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.5 $
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 * @return
49 */
50 public Map getNodes();
51
52 /***
53 * Adds a new listener to cluster events
54 *
55 * @param listener
56 */
57 public void addClusterListener(ClusterListener listener);
58
59 /***
60 * Removes a listener to cluster events
61 *
62 * @param listener
63 */
64 public void removeClusterListener(ClusterListener listener);
65
66 /***
67 * The local Node which allows you to mutate the state or subscribe to the
68 * nodes temporary queue for inbound messages direct to the Node
69 *
70 * @return
71 */
72 public LocalNode getLocalNode();
73
74
75
76
77
78 /***
79 * Sends a message to a destination, which could be to the entire group
80 * or could be a single Node's destination
81 *
82 * @param destination is either the group topic or a node's destination
83 * @param message the message to be sent
84 * @throws JMSException
85 */
86 public void send(Destination destination, Message message) throws JMSException;
87
88 /***
89 * Creates a consumer of all the messags sent to the given destination,
90 * including messages sent via the send() messages
91 *
92 * @param destination
93 * @return
94 * @throws JMSException
95 */
96 public MessageConsumer createConsumer(Destination destination) throws JMSException;
97
98 /***
99 * Creates a consumer of all message sent to the given destination,
100 * including messages sent via the send() message with an optional SQL 92 based selector to filter
101 * messages
102 *
103 * @param destination
104 * @param selector
105 * @return
106 * @throws JMSException
107 */
108 public MessageConsumer createConsumer(Destination destination, String selector) throws JMSException;
109
110 /***
111 * Creates a consumer of all message sent to the given destination,
112 * including messages sent via the send() message with an optional SQL 92 based selector to filter
113 * messages along with optionally ignoring local traffic - messages sent via the send()
114 * method on this object.
115 *
116 * @param destination the destination to consume from
117 * @param selector an optional SQL 92 filter of messages which could be null
118 * @param noLocal which if true messages sent via send() on this object will not be delivered to the consumer
119 * @return
120 * @throws JMSException
121 */
122 public MessageConsumer createConsumer(Destination destination, String selector, boolean noLocal) throws JMSException;
123
124
125
126
127
128 /***
129 * Creates a new message without a body
130 *
131 * @return
132 * @throws JMSException
133 */
134 public Message createMessage() throws JMSException;
135
136 /***
137 * Creates a new bytes message
138 *
139 * @return
140 * @throws JMSException
141 */
142 public BytesMessage createBytesMessage() throws JMSException;
143
144 /***
145 * Creates a new {@link MapMessage}
146 *
147 * @return
148 * @throws JMSException
149 */
150 public MapMessage createMapMessage() throws JMSException;
151
152 /***
153 * Creates a new {@link ObjectMessage}
154 *
155 * @return
156 * @throws JMSException
157 */
158 public ObjectMessage createObjectMessage() throws JMSException;
159
160 /***
161 * Creates a new {@link ObjectMessage}
162 *
163 * @param object
164 * @return
165 * @throws JMSException
166 */
167 public ObjectMessage createObjectMessage(Serializable object) throws JMSException;
168
169 /***
170 * Creates a new {@link StreamMessage}
171 *
172 * @return
173 * @throws JMSException
174 */
175 public StreamMessage createStreamMessage() throws JMSException;
176
177 /***
178 * Creates a new {@link TextMessage}
179 *
180 * @return
181 * @throws JMSException
182 */
183 public TextMessage createTextMessage() throws JMSException;
184
185 /***
186 * Creates a new {@link TextMessage}
187 *
188 * @param text
189 * @return
190 * @throws JMSException
191 */
192 public TextMessage createTextMessage(String text) throws JMSException;
193
194 /***
195 * wait until a the cardimality of the cluster is reaches the expected count. This method will return false if the
196 * cluster isn't started or stopped while waiting
197 *
198 * @param expectedCount the number of expected members of a cluster
199 * @param timeout timeout in milliseconds
200 * @return true if the cluster is fully connected
201 * @throws InterruptedException
202 */
203 boolean waitForClusterToComplete(int expectedCount, long timeout) throws InterruptedException;
204 }