1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the license at
* https://glassfish.dev.java.net/public/CDDLv1.0.html or
* glassfish/bootstrap/legal/CDDLv1.0.txt.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at glassfish/bootstrap/legal/CDDLv1.0.txt.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* you own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
*/
package javax.jms;
/** A client uses a <CODE>TopicPublisher</CODE> object to publish messages on a
* topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe form
* of a message producer.
*
* <P>Normally, the <CODE>Topic</CODE> is specified when a
* <CODE>TopicPublisher</CODE> is created. In this case, an attempt to use
* the <CODE>publish</CODE> methods for an unidentified
* <CODE>TopicPublisher</CODE> will throw a
* <CODE>java.lang.UnsupportedOperationException</CODE>.
*
* <P>If the <CODE>TopicPublisher</CODE> is created with an unidentified
* <CODE>Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that
* assume that the <CODE>Topic</CODE> has been identified will throw a
* <CODE>java.lang.UnsupportedOperationException</CODE>.
*
* <P>During the execution of its <CODE>publish</CODE> method,
* a message must not be changed by other threads within the client.
* If the message is modified, the result of the <CODE>publish</CODE> is
* undefined.
*
* <P>After publishing a message, a client may retain and modify it
* without affecting the message that has been published. The same message
* object may be published multiple times.
*
* <P>The following message headers are set as part of publishing a
* message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
* <code>JMSExpiration</code>, <code>JMSPriority</code>,
* <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
* When the message is published, the values of these headers are ignored.
* After completion of the <CODE>publish</CODE>, the headers hold the values
* specified by the method publishing the message. It is possible for the
* <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and
* <code>JMSTimeStamp</code> if the
* setting of these headers is explicitly disabled by the
* <code>MessageProducer.setDisableMessageID</code> or
* <code>MessageProducer.setDisableMessageTimestamp</code> method.
*
*<P>Creating a <CODE>MessageProducer</CODE> provides the same features as
* creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE> object is
* recommended when creating new code. The <CODE>TopicPublisher</CODE> is
* provided to support existing code.
*
*<P>Because <CODE>TopicPublisher</CODE> inherits from
* <CODE>MessageProducer</CODE>, it inherits the
* <CODE>send</CODE> methods that are a part of the <CODE>MessageProducer</CODE>
* interface. Using the <CODE>send</CODE> methods will have the same
* effect as using the
* <CODE>publish</CODE> methods: they are functionally the same.
*
*
* @version 1.1 February 2, 2002
* @author Mark Hapner
* @author Rich Burridge
* @author Kate Stout
*
* @see Session#createProducer(Destination)
* @see TopicSession#createPublisher(Topic)
*/
public interface TopicPublisher extends MessageProducer {
/** Gets the topic associated with this <CODE>TopicPublisher</CODE>.
*
* @return this publisher's topic
*
* @exception JMSException if the JMS provider fails to get the topic for
* this <CODE>TopicPublisher</CODE>
* due to some internal error.
*/
Topic
getTopic() throws JMSException;
/** Publishes a message to the topic.
* Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, priority,
* and time to live.
*
* @param message the message to publish
*
* @exception JMSException if the JMS provider fails to publish the message
* due to some internal error.
* @exception MessageFormatException if an invalid message is specified.
* @exception InvalidDestinationException if a client uses this method
* with a <CODE>TopicPublisher</CODE> with
* an invalid topic.
* @exception java.lang.UnsupportedOperationException if a client uses this
* method with a <CODE>TopicPublisher</CODE> that
* did not specify a topic at creation time.
*
* @see javax.jms.MessageProducer#getDeliveryMode()
* @see javax.jms.MessageProducer#getTimeToLive()
* @see javax.jms.MessageProducer#getPriority()
*/
void
publish(Message message) throws JMSException;
/** Publishes a message to the topic, specifying delivery mode,
* priority, and time to live.
*
* @param message the message to publish
* @param deliveryMode the delivery mode to use
* @param priority the priority for this message
* @param timeToLive the message's lifetime (in milliseconds)
*
* @exception JMSException if the JMS provider fails to publish the message
* due to some internal error.
* @exception MessageFormatException if an invalid message is specified.
* @exception InvalidDestinationException if a client uses this method
* with a <CODE>TopicPublisher</CODE> with
* an invalid topic.
* @exception java.lang.UnsupportedOperationException if a client uses this
* method with a <CODE>TopicPublisher</CODE> that
* did not specify a topic at creation time.
*/
void
publish(Message message,
int deliveryMode,
int priority,
long timeToLive) throws JMSException;
/** Publishes a message to a topic for an unidentified message producer.
* Uses the <CODE>TopicPublisher</CODE>'s default delivery mode,
* priority, and time to live.
*
* <P>Typically, a message producer is assigned a topic at creation
* time; however, the JMS API also supports unidentified message producers,
* which require that the topic be supplied every time a message is
* published.
*
* @param topic the topic to publish this message to
* @param message the message to publish
*
* @exception JMSException if the JMS provider fails to publish the message
* due to some internal error.
* @exception MessageFormatException if an invalid message is specified.
* @exception InvalidDestinationException if a client uses
* this method with an invalid topic.
*
* @see javax.jms.MessageProducer#getDeliveryMode()
* @see javax.jms.MessageProducer#getTimeToLive()
* @see javax.jms.MessageProducer#getPriority()
*/
void
publish(Topic topic, Message message) throws JMSException;
/** Publishes a message to a topic for an unidentified message
* producer, specifying delivery mode, priority and time to live.
*
* <P>Typically, a message producer is assigned a topic at creation
* time; however, the JMS API also supports unidentified message producers,
* which require that the topic be supplied every time a message is
* published.
*
* @param topic the topic to publish this message to
* @param message the message to publish
* @param deliveryMode the delivery mode to use
* @param priority the priority for this message
* @param timeToLive the message's lifetime (in milliseconds)
*
* @exception JMSException if the JMS provider fails to publish the message
* due to some internal error.
* @exception MessageFormatException if an invalid message is specified.
* @exception InvalidDestinationException if a client uses
* this method with an invalid topic.
*/
void
publish(Topic topic,
Message message,
int deliveryMode,
int priority,
long timeToLive) throws JMSException;
}
|
