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   {
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   
99      getTopic() throws JMSException  ;
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   message) throws JMSException  ;
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   message, 
148             int deliveryMode, 
149         int priority,
150         long timeToLive) throws JMSException  ;
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   topic, Message   message) throws JMSException  ;
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   topic, 
203             Message   message, 
204             int deliveryMode, 
205             int priority,
206         long timeToLive) throws JMSException  ;
207 }
208
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags