001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.jms;
023:
024: /** A client uses a <CODE>TopicPublisher</CODE> object to publish messages on a
025: * topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe form
026: * of a message producer.
027: *
028: * <P>Normally, the <CODE>Topic</CODE> is specified when a
029: * <CODE>TopicPublisher</CODE> is created. In this case, an attempt to use
030: * the <CODE>publish</CODE> methods for an unidentified
031: * <CODE>TopicPublisher</CODE> will throw a
032: * <CODE>java.lang.UnsupportedOperationException</CODE>.
033: *
034: * <P>If the <CODE>TopicPublisher</CODE> is created with an unidentified
035: * <CODE>Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that
036: * assume that the <CODE>Topic</CODE> has been identified will throw a
037: * <CODE>java.lang.UnsupportedOperationException</CODE>.
038: *
039: * <P>During the execution of its <CODE>publish</CODE> method,
040: * a message must not be changed by other threads within the client.
041: * If the message is modified, the result of the <CODE>publish</CODE> is
042: * undefined.
043: *
044: * <P>After publishing a message, a client may retain and modify it
045: * without affecting the message that has been published. The same message
046: * object may be published multiple times.
047: *
048: * <P>The following message headers are set as part of publishing a
049: * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
050: * <code>JMSExpiration</code>, <code>JMSPriority</code>,
051: * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
052: * When the message is published, the values of these headers are ignored.
053: * After completion of the <CODE>publish</CODE>, the headers hold the values
054: * specified by the method publishing the message. It is possible for the
055: * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and
056: * <code>JMSTimeStamp</code> if the
057: * setting of these headers is explicitly disabled by the
058: * <code>MessageProducer.setDisableMessageID</code> or
059: * <code>MessageProducer.setDisableMessageTimestamp</code> method.
060: *
061: *<P>Creating a <CODE>MessageProducer</CODE> provides the same features as
062: * creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE> object is
063: * recommended when creating new code. The <CODE>TopicPublisher</CODE> is
064: * provided to support existing code.
065:
066: *
067: *<P>Because <CODE>TopicPublisher</CODE> inherits from
068: * <CODE>MessageProducer</CODE>, it inherits the
069: * <CODE>send</CODE> methods that are a part of the <CODE>MessageProducer</CODE>
070: * interface. Using the <CODE>send</CODE> methods will have the same
071: * effect as using the
072: * <CODE>publish</CODE> methods: they are functionally the same.
073: *
074: * @see Session#createProducer(Destination)
075: * @see TopicSession#createPublisher(Topic)
076: */
077:
078: public interface TopicPublisher extends MessageProducer {
079:
080: /** Gets the topic associated with this <CODE>TopicPublisher</CODE>.
081: *
082: * @return this publisher's topic
083: *
084: * @exception JMSException if the JMS provider fails to get the topic for
085: * this <CODE>TopicPublisher</CODE>
086: * due to some internal error.
087: */
088:
089: Topic getTopic() throws JMSException;
090:
091: /** Publishes a message to the topic.
092: * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, priority,
093: * and time to live.
094: *
095: * @param message the message to publish
096: *
097: * @exception JMSException if the JMS provider fails to publish the message
098: * due to some internal error.
099: * @exception MessageFormatException if an invalid message is specified.
100: * @exception InvalidDestinationException if a client uses this method
101: * with a <CODE>TopicPublisher</CODE> with
102: * an invalid topic.
103: * @exception java.lang.UnsupportedOperationException if a client uses this
104: * method with a <CODE>TopicPublisher</CODE> that
105: * did not specify a topic at creation time.
106: *
107: * @see javax.jms.MessageProducer#getDeliveryMode()
108: * @see javax.jms.MessageProducer#getTimeToLive()
109: * @see javax.jms.MessageProducer#getPriority()
110: */
111:
112: void publish(Message message) throws JMSException;
113:
114: /** Publishes a message to the topic, specifying delivery mode,
115: * priority, and time to live.
116: *
117: * @param message the message to publish
118: * @param deliveryMode the delivery mode to use
119: * @param priority the priority for this message
120: * @param timeToLive the message's lifetime (in milliseconds)
121: *
122: * @exception JMSException if the JMS provider fails to publish the message
123: * due to some internal error.
124: * @exception MessageFormatException if an invalid message is specified.
125: * @exception InvalidDestinationException if a client uses this method
126: * with a <CODE>TopicPublisher</CODE> with
127: * an invalid topic.
128: * @exception java.lang.UnsupportedOperationException if a client uses this
129: * method with a <CODE>TopicPublisher</CODE> that
130: * did not specify a topic at creation time.
131: */
132:
133: void publish(Message message, int deliveryMode, int priority,
134: 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,
183: int priority, long timeToLive) throws JMSException;
184: }
|