Cluster xref

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 }