View Javadoc

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      // Messaging helper methods
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     // Message factory methods
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 }