001    /** 
002     * 
003     * Copyright 2004 Protique Ltd
004     * 
005     * Licensed under the Apache License, Version 2.0 (the "License"); 
006     * you may not use this file except in compliance with the License. 
007     * You may obtain a copy of the License at 
008     * 
009     * http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS, 
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
014     * See the License for the specific language governing permissions and 
015     * limitations under the License. 
016     * 
017     **/
018    
019    package org.activemq;
020    
021    import org.activemq.message.ActiveMQDestination;
022    
023    import javax.jms.Destination;
024    import javax.jms.InvalidDestinationException;
025    import javax.jms.JMSException;
026    import javax.jms.Message;
027    import javax.jms.MessageFormatException;
028    import javax.jms.Session;
029    import javax.jms.Topic;
030    import javax.jms.TopicPublisher;
031    import javax.jms.TopicSession;
032    
033    /**
034     * A client uses a <CODE>TopicPublisher</CODE> object to publish messages on
035     * a topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe
036     * form of a message producer.
037     * <p/>
038     * <P>
039     * Normally, the <CODE>Topic</CODE> is specified when a <CODE>TopicPublisher
040     * </CODE> is created. In this case, an attempt to use the <CODE>publish
041     * </CODE> methods for an unidentified <CODE>TopicPublisher</CODE> will throw
042     * a <CODE>java.lang.UnsupportedOperationException</CODE>.
043     * <p/>
044     * <P>
045     * If the <CODE>TopicPublisher</CODE> is created with an unidentified <CODE>
046     * Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that
047     * assume that the <CODE>Topic</CODE> has been identified will throw a <CODE>
048     * java.lang.UnsupportedOperationException</CODE>.
049     * <p/>
050     * <P>
051     * During the execution of its <CODE>publish</CODE> method, a message must
052     * not be changed by other threads within the client. If the message is
053     * modified, the result of the <CODE>publish</CODE> is undefined.
054     * <p/>
055     * <P>
056     * After publishing a message, a client may retain and modify it without
057     * affecting the message that has been published. The same message object may
058     * be published multiple times.
059     * <p/>
060     * <P>
061     * The following message headers are set as part of publishing a message:
062     * <code>JMSDestination</code>,<code>JMSDeliveryMode</code>,<code>JMSExpiration</code>,
063     * <code>JMSPriority</code>,<code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
064     * When the message is published, the values of these headers are ignored.
065     * After completion of the <CODE>publish</CODE>, the headers hold the values
066     * specified by the method publishing the message. It is possible for the
067     * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and
068     * <code>JMSTimeStamp</code> if the setting of these headers is explicitly
069     * disabled by the <code>MessageProducer.setDisableMessageID</code> or <code>MessageProducer.setDisableMessageTimestamp</code>
070     * method.
071     * <p/>
072     * <P>
073     * Creating a <CODE>MessageProducer</CODE> provides the same features as
074     * creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE>
075     * object is recommended when creating new code. The <CODE>TopicPublisher
076     * </CODE> is provided to support existing code.
077     * <p/>
078     * <p/>
079     * <P>
080     * Because <CODE>TopicPublisher</CODE> inherits from <CODE>MessageProducer
081     * </CODE>, it inherits the <CODE>send</CODE> methods that are a part of the
082     * <CODE>MessageProducer</CODE> interface. Using the <CODE>send</CODE>
083     * methods will have the same effect as using the <CODE>publish</CODE>
084     * methods: they are functionally the same.
085     *
086     * @see Session#createProducer(Destination)
087     * @see TopicSession#createPublisher(Topic)
088     */
089    
090    public class ActiveMQTopicPublisher extends ActiveMQMessageProducer implements
091            TopicPublisher {
092    
093        protected ActiveMQTopicPublisher(ActiveMQSession session,
094                                         ActiveMQDestination destination) throws JMSException {
095            super(session, destination);
096        }
097    
098        /**
099         * 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    }