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 }