001: /*
002: * @(#)TopicPublisher.java 1.30 02/04/09
003: *
004: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * SUN PROPRIETARY/CONFIDENTIAL.
007: * This software is the proprietary information of Sun Microsystems, Inc.
008: * Use is subject to license terms.
009: *
010: */
011:
012: package javax.jms;
013:
014: /** A client uses a <CODE>TopicPublisher</CODE> object to publish messages on a
015: * topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe form
016: * of a message producer.
017: *
018: * <P>Normally, the <CODE>Topic</CODE> is specified when a
019: * <CODE>TopicPublisher</CODE> is created. In this case, an attempt to use
020: * the <CODE>publish</CODE> methods for an unidentified
021: * <CODE>TopicPublisher</CODE> will throw a
022: * <CODE>java.lang.UnsupportedOperationException</CODE>.
023: *
024: * <P>If the <CODE>TopicPublisher</CODE> is created with an unidentified
025: * <CODE>Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that
026: * assume that the <CODE>Topic</CODE> has been identified will throw a
027: * <CODE>java.lang.UnsupportedOperationException</CODE>.
028: *
029: * <P>During the execution of its <CODE>publish</CODE> method,
030: * a message must not be changed by other threads within the client.
031: * If the message is modified, the result of the <CODE>publish</CODE> is
032: * undefined.
033: *
034: * <P>After publishing a message, a client may retain and modify it
035: * without affecting the message that has been published. The same message
036: * object may be published multiple times.
037: *
038: * <P>The following message headers are set as part of publishing a
039: * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
040: * <code>JMSExpiration</code>, <code>JMSPriority</code>,
041: * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
042: * When the message is published, the values of these headers are ignored.
043: * After completion of the <CODE>publish</CODE>, the headers hold the values
044: * specified by the method publishing the message. It is possible for the
045: * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and
046: * <code>JMSTimeStamp</code> if the
047: * setting of these headers is explicitly disabled by the
048: * <code>MessageProducer.setDisableMessageID</code> or
049: * <code>MessageProducer.setDisableMessageTimestamp</code> method.
050: *
051: *<P>Creating a <CODE>MessageProducer</CODE> provides the same features as
052: * creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE> object is
053: * recommended when creating new code. The <CODE>TopicPublisher</CODE> is
054: * provided to support existing code.
055:
056: *
057: *<P>Because <CODE>TopicPublisher</CODE> inherits from
058: * <CODE>MessageProducer</CODE>, it inherits the
059: * <CODE>send</CODE> methods that are a part of the <CODE>MessageProducer</CODE>
060: * interface. Using the <CODE>send</CODE> methods will have the same
061: * effect as using the
062: * <CODE>publish</CODE> methods: they are functionally the same.
063: *
064: *
065: * @version 1.1 February 2, 2002
066: * @author Mark Hapner
067: * @author Rich Burridge
068: * @author Kate Stout
069: *
070: * @see Session#createProducer(Destination)
071: * @see TopicSession#createPublisher(Topic)
072: */
073:
074: public interface TopicPublisher extends MessageProducer {
075:
076: /** Gets the topic associated with this <CODE>TopicPublisher</CODE>.
077: *
078: * @return this publisher's topic
079: *
080: * @exception JMSException if the JMS provider fails to get the topic for
081: * this <CODE>TopicPublisher</CODE>
082: * due to some internal error.
083: */
084:
085: Topic getTopic() throws JMSException;
086:
087: /** Publishes a message to the topic.
088: * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, priority,
089: * and time to live.
090: *
091: * @param message the message to publish
092: *
093: * @exception JMSException if the JMS provider fails to publish the message
094: * due to some internal error.
095: * @exception MessageFormatException if an invalid message is specified.
096: * @exception InvalidDestinationException if a client uses this method
097: * with a <CODE>TopicPublisher</CODE> with
098: * an invalid topic.
099: * @exception java.lang.UnsupportedOperationException if a client uses this
100: * method with a <CODE>TopicPublisher</CODE> that
101: * did not specify a topic at creation time.
102: *
103: * @see javax.jms.MessageProducer#getDeliveryMode()
104: * @see javax.jms.MessageProducer#getTimeToLive()
105: * @see javax.jms.MessageProducer#getPriority()
106: */
107:
108: void publish(Message message) throws JMSException;
109:
110: /** Publishes a message to the topic, specifying delivery mode,
111: * priority, and time to live.
112: *
113: * @param message the message to publish
114: * @param deliveryMode the delivery mode to use
115: * @param priority the priority for this message
116: * @param timeToLive the message's lifetime (in milliseconds)
117: *
118: * @exception JMSException if the JMS provider fails to publish the message
119: * due to some internal error.
120: * @exception MessageFormatException if an invalid message is specified.
121: * @exception InvalidDestinationException if a client uses this method
122: * with a <CODE>TopicPublisher</CODE> with
123: * an invalid topic.
124: * @exception java.lang.UnsupportedOperationException if a client uses this
125: * method with a <CODE>TopicPublisher</CODE> that
126: * did not specify a topic at creation time.
127: */
128:
129: void publish(Message message, int deliveryMode, int priority,
130: long timeToLive) throws JMSException;
131:
132: /** Publishes a message to a topic for an unidentified message producer.
133: * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode,
134: * priority, and time to live.
135: *
136: * <P>Typically, a message producer is assigned a topic at creation
137: * time; however, the JMS API also supports unidentified message producers,
138: * which require that the topic be supplied every time a message is
139: * published.
140: *
141: * @param topic the topic to publish this message to
142: * @param message the message to publish
143: *
144: * @exception JMSException if the JMS provider fails to publish the message
145: * due to some internal error.
146: * @exception MessageFormatException if an invalid message is specified.
147: * @exception InvalidDestinationException if a client uses
148: * this method with an invalid topic.
149: *
150: * @see javax.jms.MessageProducer#getDeliveryMode()
151: * @see javax.jms.MessageProducer#getTimeToLive()
152: * @see javax.jms.MessageProducer#getPriority()
153: */
154:
155: void publish(Topic topic, Message message) throws JMSException;
156:
157: /** Publishes a message to a topic for an unidentified message
158: * producer, specifying delivery mode, priority and time to live.
159: *
160: * <P>Typically, a message producer is assigned a topic at creation
161: * time; however, the JMS API also supports unidentified message producers,
162: * which require that the topic be supplied every time a message is
163: * published.
164: *
165: * @param topic the topic to publish this message to
166: * @param message the message to publish
167: * @param deliveryMode the delivery mode to use
168: * @param priority the priority for this message
169: * @param timeToLive the message's lifetime (in milliseconds)
170: *
171: * @exception JMSException if the JMS provider fails to publish the message
172: * due to some internal error.
173: * @exception MessageFormatException if an invalid message is specified.
174: * @exception InvalidDestinationException if a client uses
175: * this method with an invalid topic.
176: */
177:
178: void publish(Topic topic, Message message, int deliveryMode,
179: int priority, long timeToLive) throws JMSException;
180: }
|