KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jms > TopicPublisher


1 /*
2  * The contents of this file are subject to the terms
3  * of the Common Development and Distribution License
4  * (the License). You may not use this file except in
5  * compliance with the License.
6  *
7  * You can obtain a copy of the license at
8  * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9  * glassfish/bootstrap/legal/CDDLv1.0.txt.
10  * See the License for the specific language governing
11  * permissions and limitations under the License.
12  *
13  * When distributing Covered Code, include this CDDL
14  * Header Notice in each file and include the License file
15  * at glassfish/bootstrap/legal/CDDLv1.0.txt.
16  * If applicable, add the following below the CDDL Header,
17  * with the fields enclosed by brackets [] replaced by
18  * you own identifying information:
19  * "Portions Copyrighted [year] [name of copyright owner]"
20  *
21  * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22  */

23
24
25 package javax.jms;
26
27 /** A client uses a <CODE>TopicPublisher</CODE> object to publish messages on a
28   * topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe form
29   * of a message producer.
30   *
31   * <P>Normally, the <CODE>Topic</CODE> is specified when a
32   * <CODE>TopicPublisher</CODE> is created. In this case, an attempt to use
33   * the <CODE>publish</CODE> methods for an unidentified
34   * <CODE>TopicPublisher</CODE> will throw a
35   * <CODE>java.lang.UnsupportedOperationException</CODE>.
36   *
37   * <P>If the <CODE>TopicPublisher</CODE> is created with an unidentified
38   * <CODE>Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that
39   * assume that the <CODE>Topic</CODE> has been identified will throw a
40   * <CODE>java.lang.UnsupportedOperationException</CODE>.
41   *
42   * <P>During the execution of its <CODE>publish</CODE> method,
43   * a message must not be changed by other threads within the client.
44   * If the message is modified, the result of the <CODE>publish</CODE> is
45   * undefined.
46   *
47   * <P>After publishing a message, a client may retain and modify it
48   * without affecting the message that has been published. The same message
49   * object may be published multiple times.
50   *
51   * <P>The following message headers are set as part of publishing a
52   * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
53   * <code>JMSExpiration</code>, <code>JMSPriority</code>,
54   * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
55   * When the message is published, the values of these headers are ignored.
56   * After completion of the <CODE>publish</CODE>, the headers hold the values
57   * specified by the method publishing the message. It is possible for the
58   * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and
59   * <code>JMSTimeStamp</code> if the
60   * setting of these headers is explicitly disabled by the
61   * <code>MessageProducer.setDisableMessageID</code> or
62   * <code>MessageProducer.setDisableMessageTimestamp</code> method.
63   *
64   *<P>Creating a <CODE>MessageProducer</CODE> provides the same features as
65   * creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE> object is
66   * recommended when creating new code. The <CODE>TopicPublisher</CODE> is
67   * provided to support existing code.
68
69   *
70   *<P>Because <CODE>TopicPublisher</CODE> inherits from
71   * <CODE>MessageProducer</CODE>, it inherits the
72   * <CODE>send</CODE> methods that are a part of the <CODE>MessageProducer</CODE>
73   * interface. Using the <CODE>send</CODE> methods will have the same
74   * effect as using the
75   * <CODE>publish</CODE> methods: they are functionally the same.
76   *
77   *
78   * @version 1.1 February 2, 2002
79   * @author Mark Hapner
80   * @author Rich Burridge
81   * @author Kate Stout
82   *
83   * @see Session#createProducer(Destination)
84   * @see TopicSession#createPublisher(Topic)
85   */

86
87 public interface TopicPublisher extends MessageProducer JavaDoc {
88
89     /** Gets the topic associated with this <CODE>TopicPublisher</CODE>.
90       *
91       * @return this publisher's topic
92       *
93       * @exception JMSException if the JMS provider fails to get the topic for
94       * this <CODE>TopicPublisher</CODE>
95       * due to some internal error.
96       */

97
98     Topic JavaDoc
99     getTopic() throws JMSException JavaDoc;
100
101  
102     /** Publishes a message to the topic.
103       * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, priority,
104       * and time to live.
105       *
106       * @param message the message to publish
107       *
108       * @exception JMSException if the JMS provider fails to publish the message
109       * due to some internal error.
110       * @exception MessageFormatException if an invalid message is specified.
111       * @exception InvalidDestinationException if a client uses this method
112       * with a <CODE>TopicPublisher</CODE> with
113       * an invalid topic.
114       * @exception java.lang.UnsupportedOperationException if a client uses this
115       * method with a <CODE>TopicPublisher</CODE> that
116       * did not specify a topic at creation time.
117       *
118       * @see javax.jms.MessageProducer#getDeliveryMode()
119       * @see javax.jms.MessageProducer#getTimeToLive()
120       * @see javax.jms.MessageProducer#getPriority()
121       */

122
123     void
124     publish(Message JavaDoc message) throws JMSException JavaDoc;
125
126
127     /** Publishes a message to the topic, specifying delivery mode,
128       * priority, and time to live.
129       *
130       * @param message the message to publish
131       * @param deliveryMode the delivery mode to use
132       * @param priority the priority for this message
133       * @param timeToLive the message's lifetime (in milliseconds)
134       *
135       * @exception JMSException if the JMS provider fails to publish the message
136       * due to some internal error.
137       * @exception MessageFormatException if an invalid message is specified.
138       * @exception InvalidDestinationException if a client uses this method
139       * with a <CODE>TopicPublisher</CODE> with
140       * an invalid topic.
141       * @exception java.lang.UnsupportedOperationException if a client uses this
142       * method with a <CODE>TopicPublisher</CODE> that
143       * did not specify a topic at creation time.
144       */

145  
146     void
147     publish(Message JavaDoc message,
148             int deliveryMode,
149         int priority,
150         long timeToLive) throws JMSException JavaDoc;
151
152
153     /** Publishes a message to a topic for an unidentified message producer.
154       * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode,
155       * priority, and time to live.
156       *
157       * <P>Typically, a message producer is assigned a topic at creation
158       * time; however, the JMS API also supports unidentified message producers,
159       * which require that the topic be supplied every time a message is
160       * published.
161       *
162       * @param topic the topic to publish this message to
163       * @param message the message to publish
164       *
165       * @exception JMSException if the JMS provider fails to publish the message
166       * due to some internal error.
167       * @exception MessageFormatException if an invalid message is specified.
168       * @exception InvalidDestinationException if a client uses
169       * this method with an invalid topic.
170       *
171       * @see javax.jms.MessageProducer#getDeliveryMode()
172       * @see javax.jms.MessageProducer#getTimeToLive()
173       * @see javax.jms.MessageProducer#getPriority()
174       */

175
176     void
177     publish(Topic JavaDoc topic, Message JavaDoc message) throws JMSException JavaDoc;
178
179
180     /** Publishes a message to a topic for an unidentified message
181       * producer, specifying delivery mode, priority and time to live.
182       *
183       * <P>Typically, a message producer is assigned a topic at creation
184       * time; however, the JMS API also supports unidentified message producers,
185       * which require that the topic be supplied every time a message is
186       * published.
187       *
188       * @param topic the topic to publish this message to
189       * @param message the message to publish
190       * @param deliveryMode the delivery mode to use
191       * @param priority the priority for this message
192       * @param timeToLive the message's lifetime (in milliseconds)
193       *
194       * @exception JMSException if the JMS provider fails to publish the message
195       * due to some internal error.
196       * @exception MessageFormatException if an invalid message is specified.
197       * @exception InvalidDestinationException if a client uses
198       * this method with an invalid topic.
199       */

200
201     void
202     publish(Topic JavaDoc topic,
203             Message JavaDoc message,
204             int deliveryMode,
205             int priority,
206         long timeToLive) throws JMSException JavaDoc;
207 }
208
Popular Tags