1 /*
2 * JBoss, Home of Professional Open Source
3 * Copyright 2005, JBoss Inc., and individual contributors as indicated
4 * by the @authors tag. See the copyright.txt in the distribution for a
5 * full listing of individual contributors.
6 *
7 * This is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU Lesser General Public License as
9 * published by the Free Software Foundation; either version 2.1 of
10 * the License, or (at your option) any later version.
11 *
12 * This software is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this software; if not, write to the Free
19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21 */
22 package javax.jms;
23
24 /** A client uses a <CODE>TopicPublisher</CODE> object to publish messages on a
25 * topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe form
26 * of a message producer.
27 *
28 * <P>Normally, the <CODE>Topic</CODE> is specified when a
29 * <CODE>TopicPublisher</CODE> is created. In this case, an attempt to use
30 * the <CODE>publish</CODE> methods for an unidentified
31 * <CODE>TopicPublisher</CODE> will throw a
32 * <CODE>java.lang.UnsupportedOperationException</CODE>.
33 *
34 * <P>If the <CODE>TopicPublisher</CODE> is created with an unidentified
35 * <CODE>Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that
36 * assume that the <CODE>Topic</CODE> has been identified will throw a
37 * <CODE>java.lang.UnsupportedOperationException</CODE>.
38 *
39 * <P>During the execution of its <CODE>publish</CODE> method,
40 * a message must not be changed by other threads within the client.
41 * If the message is modified, the result of the <CODE>publish</CODE> is
42 * undefined.
43 *
44 * <P>After publishing a message, a client may retain and modify it
45 * without affecting the message that has been published. The same message
46 * object may be published multiple times.
47 *
48 * <P>The following message headers are set as part of publishing a
49 * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
50 * <code>JMSExpiration</code>, <code>JMSPriority</code>,
51 * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
52 * When the message is published, the values of these headers are ignored.
53 * After completion of the <CODE>publish</CODE>, the headers hold the values
54 * specified by the method publishing the message. It is possible for the
55 * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and
56 * <code>JMSTimeStamp</code> if the
57 * setting of these headers is explicitly disabled by the
58 * <code>MessageProducer.setDisableMessageID</code> or
59 * <code>MessageProducer.setDisableMessageTimestamp</code> method.
60 *
61 *<P>Creating a <CODE>MessageProducer</CODE> provides the same features as
62 * creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE> object is
63 * recommended when creating new code. The <CODE>TopicPublisher</CODE> is
64 * provided to support existing code.
65
66 *
67 *<P>Because <CODE>TopicPublisher</CODE> inherits from
68 * <CODE>MessageProducer</CODE>, it inherits the
69 * <CODE>send</CODE> methods that are a part of the <CODE>MessageProducer</CODE>
70 * interface. Using the <CODE>send</CODE> methods will have the same
71 * effect as using the
72 * <CODE>publish</CODE> methods: they are functionally the same.
73 *
74 * @see Session#createProducer(Destination)
75 * @see TopicSession#createPublisher(Topic)
76 */
77
78 public interface TopicPublisher extends MessageProducer
79 {
80
81 /** Gets the topic associated with this <CODE>TopicPublisher</CODE>.
82 *
83 * @return this publisher's topic
84 *
85 * @exception JMSException if the JMS provider fails to get the topic for
86 * this <CODE>TopicPublisher</CODE>
87 * due to some internal error.
88 */
89
90 Topic getTopic() throws JMSException;
91
92 /** Publishes a message to the topic.
93 * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, priority,
94 * and time to live.
95 *
96 * @param message the message to publish
97 *
98 * @exception JMSException if the JMS provider fails to publish the message
99 * due to some internal error.
100 * @exception MessageFormatException if an invalid message is specified.
101 * @exception InvalidDestinationException if a client uses this method
102 * with a <CODE>TopicPublisher</CODE> with
103 * an invalid topic.
104 * @exception java.lang.UnsupportedOperationException if a client uses this
105 * method with a <CODE>TopicPublisher</CODE> that
106 * did not specify a topic at creation time.
107 *
108 * @see javax.jms.MessageProducer#getDeliveryMode()
109 * @see javax.jms.MessageProducer#getTimeToLive()
110 * @see javax.jms.MessageProducer#getPriority()
111 */
112
113 void publish(Message message) throws JMSException;
114
115 /** Publishes a message to the topic, specifying delivery mode,
116 * priority, and time to live.
117 *
118 * @param message the message to publish
119 * @param deliveryMode the delivery mode to use
120 * @param priority the priority for this message
121 * @param timeToLive the message's lifetime (in milliseconds)
122 *
123 * @exception JMSException if the JMS provider fails to publish the message
124 * due to some internal error.
125 * @exception MessageFormatException if an invalid message is specified.
126 * @exception InvalidDestinationException if a client uses this method
127 * with a <CODE>TopicPublisher</CODE> with
128 * an invalid topic.
129 * @exception java.lang.UnsupportedOperationException if a client uses this
130 * method with a <CODE>TopicPublisher</CODE> that
131 * did not specify a topic at creation time.
132 */
133
134 void publish(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
135
136 /** Publishes a message to a topic for an unidentified message producer.
137 * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode,
138 * priority, and time to live.
139 *
140 * <P>Typically, a message producer is assigned a topic at creation
141 * time; however, the JMS API also supports unidentified message producers,
142 * which require that the topic be supplied every time a message is
143 * published.
144 *
145 * @param topic the topic to publish this message to
146 * @param message the message to publish
147 *
148 * @exception JMSException if the JMS provider fails to publish the message
149 * due to some internal error.
150 * @exception MessageFormatException if an invalid message is specified.
151 * @exception InvalidDestinationException if a client uses
152 * this method with an invalid topic.
153 *
154 * @see javax.jms.MessageProducer#getDeliveryMode()
155 * @see javax.jms.MessageProducer#getTimeToLive()
156 * @see javax.jms.MessageProducer#getPriority()
157 */
158
159 void publish(Topic topic, Message message) throws JMSException;
160
161 /** Publishes a message to a topic for an unidentified message
162 * producer, specifying delivery mode, priority and time to live.
163 *
164 * <P>Typically, a message producer is assigned a topic at creation
165 * time; however, the JMS API also supports unidentified message producers,
166 * which require that the topic be supplied every time a message is
167 * published.
168 *
169 * @param topic the topic to publish this message to
170 * @param message the message to publish
171 * @param deliveryMode the delivery mode to use
172 * @param priority the priority for this message
173 * @param timeToLive the message's lifetime (in milliseconds)
174 *
175 * @exception JMSException if the JMS provider fails to publish the message
176 * due to some internal error.
177 * @exception MessageFormatException if an invalid message is specified.
178 * @exception InvalidDestinationException if a client uses
179 * this method with an invalid topic.
180 */
181
182 void publish(Topic topic, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
183 }
Save This Page