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;
    20
    21  import org.codehaus.activemq.message.ActiveMQDestination;
    22
    23  import javax.jms.Destination;
    24  import javax.jms.InvalidDestinationException;
    25  import javax.jms.JMSException;
    26  import javax.jms.Message;
    27  import javax.jms.MessageFormatException;
    28  import javax.jms.Session;
    29  import javax.jms.Topic;
    30  import javax.jms.TopicPublisher;
    31  import javax.jms.TopicSession;
    32
    33  /***
    34   * A client uses a <CODE>TopicPublisher</CODE> object to publish messages on
    35   * a topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe
    36   * form of a message producer.
    37   * <p/>
    38   * <P>
    39   * Normally, the <CODE>Topic</CODE> is specified when a <CODE>TopicPublisher
    40   * </CODE> is created. In this case, an attempt to use the <CODE>publish
    41   * </CODE> methods for an unidentified <CODE>TopicPublisher</CODE> will throw
    42   * a <CODE>java.lang.UnsupportedOperationException</CODE>.
    43   * <p/>
    44   * <P>
    45   * If the <CODE>TopicPublisher</CODE> is created with an unidentified <CODE>
    46   * Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that
    47   * assume that the <CODE>Topic</CODE> has been identified will throw a <CODE>
    48   * java.lang.UnsupportedOperationException</CODE>.
    49   * <p/>
    50   * <P>
    51   * During the execution of its <CODE>publish</CODE> method, a message must
    52   * not be changed by other threads within the client. If the message is
    53   * modified, the result of the <CODE>publish</CODE> is undefined.
    54   * <p/>
    55   * <P>
    56   * After publishing a message, a client may retain and modify it without
    57   * affecting the message that has been published. The same message object may
    58   * be published multiple times.
    59   * <p/>
    60   * <P>
    61   * The following message headers are set as part of publishing a message:
    62   * <code>JMSDestination</code>,<code>JMSDeliveryMode</code>,<code>JMSExpiration</code>,
    63   * <code>JMSPriority</code>,<code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
    64   * When the message is published, the values of these headers are ignored.
    65   * After completion of the <CODE>publish</CODE>, the headers hold the values
    66   * specified by the method publishing the message. It is possible for the
    67   * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and
    68   * <code>JMSTimeStamp</code> if the setting of these headers is explicitly
    69   * disabled by the <code>MessageProducer.setDisableMessageID</code> or <code>MessageProducer.setDisableMessageTimestamp</code>
    70   * method.
    71   * <p/>
    72   * <P>
    73   * Creating a <CODE>MessageProducer</CODE> provides the same features as
    74   * creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE>
    75   * object is recommended when creating new code. The <CODE>TopicPublisher
    76   * </CODE> is provided to support existing code.
    77   * <p/>
    78   * <p/>
    79   * <P>
    80   * Because <CODE>TopicPublisher</CODE> inherits from <CODE>MessageProducer
    81   * </CODE>, it inherits the <CODE>send</CODE> methods that are a part of the
    82   * <CODE>MessageProducer</CODE> interface. Using the <CODE>send</CODE>
    83   * methods will have the same effect as using the <CODE>publish</CODE>
    84   * methods: they are functionally the same.
    85   *
    86   * @see Session#createProducer(Destination)
    87   * @see TopicSession#createPublisher(Topic)
    88   */
    89
    90  public class ActiveMQTopicPublisher extends ActiveMQMessageProducer implements
    91          TopicPublisher {
    92
    93      protected ActiveMQTopicPublisher(ActiveMQSession session,
    94                                       ActiveMQDestination destination) throws JMSException {
    95          super(session, destination);
    96      }
    97
    98      /***
    99       * Gets the topic associated with this <CODE>TopicPublisher</CODE>.
    100      *
    101      * @return this publisher's topic
    102      * @throws JMSException if the JMS provider fails to get the topic for this
    103      *                      <CODE>TopicPublisher</CODE> due to some internal error.
    104      */
    105
    106     public Topic getTopic() throws JMSException {
    107         return (Topic) super.getDestination();
    108     }
    109
    110     /***
    111      * Publishes a message to the topic. Uses the <CODE>TopicPublisher</CODE>'s
    112      * default delivery mode, priority, and time to live.
    113      *
    114      * @param message the message to publish
    115      * @throws JMSException                if the JMS provider fails to publish the message due to
    116      *                                     some internal error.
    117      * @throws MessageFormatException      if an invalid message is specified.
    118      * @throws InvalidDestinationException if a client uses this method with a <CODE>TopicPublisher
    119      *                                     </CODE> with an invalid topic.
    120      * @throws java.lang.UnsupportedOperationException
    121      *                                     if a client uses this method with a <CODE>TopicPublisher
    122      *                                     </CODE> that did not specify a topic at creation time.
    123      * @see javax.jms.MessageProducer#getDeliveryMode()
    124      * @see javax.jms.MessageProducer#getTimeToLive()
    125      * @see javax.jms.MessageProducer#getPriority()
    126      */
    127
    128     public void publish(Message message) throws JMSException {
    129         super.send(message);
    130     }
    131
    132     /***
    133      * Publishes a message to the topic, specifying delivery mode, priority,
    134      * and time to live.
    135      *
    136      * @param message      the message to publish
    137      * @param deliveryMode the delivery mode to use
    138      * @param priority     the priority for this message
    139      * @param timeToLive   the message's lifetime (in milliseconds)
    140      * @throws JMSException                if the JMS provider fails to publish the message due to
    141      *                                     some internal error.
    142      * @throws MessageFormatException      if an invalid message is specified.
    143      * @throws InvalidDestinationException if a client uses this method with a <CODE>TopicPublisher
    144      *                                     </CODE> with an invalid topic.
    145      * @throws java.lang.UnsupportedOperationException
    146      *                                     if a client uses this method with a <CODE>TopicPublisher
    147      *                                     </CODE> that did not specify a topic at creation time.
    148      */
    149
    150     public void publish(Message message, int deliveryMode, int priority,
    151                         long timeToLive) throws JMSException {
    152         super.send(message, deliveryMode, priority, timeToLive);
    153     }
    154
    155     /***
    156      * Publishes a message to a topic for an unidentified message producer.
    157      * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode,
    158      * priority, and time to live.
    159      * <p/>
    160      * <P>
    161      * Typically, a message producer is assigned a topic at creation time;
    162      * however, the JMS API also supports unidentified message producers, which
    163      * require that the topic be supplied every time a message is published.
    164      *
    165      * @param topic   the topic to publish this message to
    166      * @param message the message to publish
    167      * @throws JMSException                if the JMS provider fails to publish the message due to
    168      *                                     some internal error.
    169      * @throws MessageFormatException      if an invalid message is specified.
    170      * @throws InvalidDestinationException if a client uses this method with an invalid topic.
    171      * @see javax.jms.MessageProducer#getDeliveryMode()
    172      * @see javax.jms.MessageProducer#getTimeToLive()
    173      * @see javax.jms.MessageProducer#getPriority()
    174      */
    175
    176     public void publish(Topic topic, Message message) throws JMSException {
    177         super.send(topic, message);
    178     }
    179
    180     /***
    181      * Publishes a message to a topic for an unidentified message producer,
    182      * specifying delivery mode, priority and time to live.
    183      * <p/>
    184      * <P>
    185      * Typically, a message producer is assigned a topic at creation time;
    186      * however, the JMS API also supports unidentified message producers, which
    187      * require that the topic be supplied every time a message is published.
    188      *
    189      * @param topic        the topic to publish this message to
    190      * @param message      the message to publish
    191      * @param deliveryMode the delivery mode to use
    192      * @param priority     the priority for this message
    193      * @param timeToLive   the message's lifetime (in milliseconds)
    194      * @throws JMSException                if the JMS provider fails to publish the message due to
    195      *                                     some internal error.
    196      * @throws MessageFormatException      if an invalid message is specified.
    197      * @throws InvalidDestinationException if a client uses this method with an invalid topic.
    198      */
    199
    200     public void publish(Topic topic, Message message, int deliveryMode,
    201                         int priority, long timeToLive) throws JMSException {
    202         super.send(topic, message, deliveryMode, priority, timeToLive);
    203     }
    204 }