KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > activemq > ActiveMQTopicPublisher


1 /**
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one or more
4  * contributor license agreements. See the NOTICE file distributed with
5  * this work for additional information regarding copyright ownership.
6  * The ASF licenses this file to You under the Apache License, Version 2.0
7  * (the "License"); you may not use this file except in compliance with
8  * the License. You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18
19 package org.apache.activemq;
20
21 import org.apache.activemq.command.ActiveMQDestination;
22
23 import javax.jms.Destination JavaDoc;
24 import javax.jms.InvalidDestinationException JavaDoc;
25 import javax.jms.JMSException JavaDoc;
26 import javax.jms.Message JavaDoc;
27 import javax.jms.MessageFormatException JavaDoc;
28 import javax.jms.Session JavaDoc;
29 import javax.jms.Topic JavaDoc;
30 import javax.jms.TopicPublisher JavaDoc;
31 import javax.jms.TopicSession JavaDoc;
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 JavaDoc {
92
93     protected ActiveMQTopicPublisher(ActiveMQSession session,
94                                      ActiveMQDestination destination) throws JMSException JavaDoc {
95         super(session, session.getNextProducerId(), 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 JavaDoc getTopic() throws JMSException JavaDoc {
107         return (Topic JavaDoc) 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 JavaDoc {
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 JavaDoc {
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 JavaDoc topic, Message message) throws JMSException JavaDoc {
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 JavaDoc topic, Message message, int deliveryMode,
201                         int priority, long timeToLive) throws JMSException JavaDoc {
202         super.send(topic, message, deliveryMode, priority, timeToLive);
203     }
204 }
205
Popular Tags