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.activemq.service;
    20
    21  import org.codehaus.activemq.broker.BrokerClient;
    22  import org.codehaus.activemq.message.ActiveMQDestination;
    23  import org.codehaus.activemq.message.ActiveMQMessage;
    24  import org.codehaus.activemq.message.ConsumerInfo;
    25  import org.codehaus.activemq.message.MessageAck;
    26
    27  import javax.jms.JMSException;
    28
    29
    30  /***
    31   * A Subscription holds messages to be dispatched to a a Client Consumer
    32   *
    33   * @version $Revision: 1.15 $
    34   */
    35  public interface Subscription {
    36
    37
    38      /***
    39       * Set the active consumer info
    40       * @param client
    41       *
    42       * @param info
    43       */
    44      public void setActiveConsumer(BrokerClient client,ConsumerInfo info);
    45
    46      /***
    47       * Called when the Subscription is discarded
    48       *
    49       * @throws JMSException
    50       */
    51      public void clear() throws JMSException;
    52
    53      /***
    54       * Called when an active message consumer has closed.
    55       *
    56       * @throws JMSException
    57       */
    58
    59      public void reset() throws JMSException;
    60
    61      /***
    62       * @return Returns the clientId.
    63       */
    64      public String getClientId();
    65
    66      /***
    67       * @return Returns the subscriberName.
    68       */
    69      public String getSubscriberName();
    70
    71      /***
    72       * @return Returns the destination.
    73       */
    74      public ActiveMQDestination getDestination();
    75
    76      /***
    77       * @return Returns the selector.
    78       */
    79      public String getSelector();
    80
    81      /***
    82       * @return Returns true if an active message consumer is associated with this
    83       */
    84      public boolean isActive();
    85
    86      /***
    87       * set the state of the Subscription
    88       *
    89       * @param newActive
    90       */
    91      public void setActive(boolean newActive) throws JMSException;
    92
    93      /***
    94       * @return Returns the consumerNumber.
    95       */
    96      public int getConsumerNumber();
    97
    98      /***
    99       * @return the consumer Id for the active consumer
    100      */
    101     public String getConsumerId();
    102
    103     /***
    104      * determines if the Subscription is interested in the message
    105      *
    106      * @param message
    107      * @return
    108      * @throws JMSException
    109      */
    110     public boolean isTarget(ActiveMQMessage message) throws JMSException;
    111
    112
    113     /***
    114      * If the Subscription is a target for the message, the subscription will add a reference to
    115      * the message and register an interest in the message to the container
    116      *
    117      * @param container
    118      * @param message
    119      * @throws JMSException
    120      */
    121
    122     public void addMessage(MessageContainer container, ActiveMQMessage message) throws JMSException;
    123
    124     /***
    125      * Indicates a message has been delivered to a MessageConsumer
    126      * which is typically called for topic based subscriptions
    127      *
    128      * @param ack
    129      * @throws JMSException
    130      */
    131
    132     public void messageConsumed(MessageAck ack) throws JMSException;
    133
    134     /***
    135      * Forces the given message to be redelivered
    136      *
    137      * @param container
    138      * @param ack
    139      */
    140     public void redeliverMessage(MessageContainer container, MessageAck ack) throws JMSException;
    141
    142     /***
    143      * Retrieve messages to dispatch
    144      *
    145      * @return
    146      * @throws JMSException
    147      */
    148
    149     public ActiveMQMessage[] getMessagesToDispatch() throws JMSException;
    150
    151     /***
    152      * Indicates if this Subscription has more messages to send to the
    153      * Consumer
    154      *
    155      * @return true if more messages available to dispatch
    156      * @throws JMSException
    157      */
    158     public boolean isReadyToDispatch() throws JMSException;
    159
    160     /***
    161      * Indicates the Subscription it's reached it's pre-fetch limit
    162      *
    163      * @return true/false
    164      * @throws JMSException
    165      */
    166     public boolean isAtPrefetchLimit() throws JMSException;
    167
    168
    169     /***
    170      * Indicates the Consumer is a Durable Subscriber
    171      *
    172      * @return
    173      * @throws JMSException
    174      */
    175     public boolean isDurableTopic() throws JMSException;
    176
    177     /***
    178      * Indicates the consumer is a browser only
    179      *
    180      * @return true if a Browser
    181      * @throws JMSException
    182      */
    183     public boolean isBrowser() throws JMSException;
    184
    185
    186     /***
    187      * Retreives the messageIdentity of the last message sent to this
    188      * Queue based Subscription
    189      *
    190      * @return the messageId of the last message or null
    191      * @throws JMSException
    192      */
    193     public MessageIdentity getLastMessageIdentity() throws JMSException;
    194
    195
    196     /***
    197      * Used for a Queue based Subscription to set the last acknowledged
    198      * message ID
    199      *
    200      * @param messageIdentity
    201      * @throws JMSException
    202      */
    203     public void setLastMessageIdentifier(MessageIdentity messageIdentity) throws JMSException;
    204
    205
    206     public boolean isWildcard();
    207
    208     /***
    209      * Returns the persistent key used to uniquely identify this durable topic subscription
    210      *
    211      * @return
    212      */
    213     public String getPersistentKey();
    214
    215     /***
    216      * Checks if this subscription is a duplicate durable subscription of the given consumer info
    217      *
    218      * @param info
    219      * @return true if this subscription is a durable topic subscription and the clientID and consumer
    220      *         names match
    221      */
    222     public boolean isSameDurableSubscription(ConsumerInfo info) throws JMSException;
    223
    224     /***
    225      * We have not yet committed and so the message acknowledgement has not really occurred yet
    226      * but we need to let the dispatcher know that we can commence dispatching more messages
    227      * to the client. This is so that we can have a prefetch value of 1 yet we can still consume
    228      * 1000 messages inside a transaction, with all the acks coming after the commit() on the client.
    229      *
    230      * @param ack
    231      */
    232     public void onAcknowledgeTransactedMessageBeforeCommit(MessageAck ack) throws JMSException;
    233
    234     /***
    235      * Lazily creates the persistent entry representation of this subscription
    236      */
    237     public SubscriberEntry getSubscriptionEntry();
    238 }