1. /*

  2.  * Copyright 2002 Sun Microsystems, Inc. All rights reserved.

  3.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  4.  */

  5. 

  6. package javax.jms;

  7. 

  8. /** A client uses a <CODE>TopicPublisher</CODE> object to publish messages on a 

  9.   * topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe form

  10.   * of a message producer.

  11.   *

  12.   * <P>Normally, the <CODE>Topic</CODE> is specified when a 

  13.   * <CODE>TopicPublisher</CODE> is created.  In this case, an attempt to use 

  14.   * the <CODE>publish</CODE> methods for an unidentified 

  15.   * <CODE>TopicPublisher</CODE> will throw a 

  16.   * <CODE>java.lang.UnsupportedOperationException</CODE>.

  17.   *

  18.   * <P>If the <CODE>TopicPublisher</CODE> is created with an unidentified 

  19.   * <CODE>Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that 

  20.   * assume that the <CODE>Topic</CODE> has been identified will throw a 

  21.   * <CODE>java.lang.UnsupportedOperationException</CODE>.

  22.   *

  23.   * <P>During the execution of its <CODE>publish</CODE> method,

  24.   * a message must not be changed by other threads within the client. 

  25.   * If the message is modified, the result of the <CODE>publish</CODE> is 

  26.   * undefined.

  27.   * 

  28.   * <P>After publishing a message, a client may retain and modify it

  29.   * without affecting the message that has been published. The same message

  30.   * object may be published multiple times.

  31.   * 

  32.   * <P>The following message headers are set as part of publishing a 

  33.   * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>, 

  34.   * <code>JMSExpiration</code>, <code>JMSPriority</code>, 

  35.   * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.

  36.   * When the message is published, the values of these headers are ignored. 

  37.   * After completion of the <CODE>publish</CODE>, the headers hold the values 

  38.   * specified by the method publishing the message. It is possible for the 

  39.   * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and 

  40.   * <code>JMSTimeStamp</code> if the 

  41.   * setting of these headers is explicitly disabled by the 

  42.   * <code>MessageProducer.setDisableMessageID</code> or

  43.   * <code>MessageProducer.setDisableMessageTimestamp</code> method.

  44.   *

  45.   * @version     1.0 - 4 August 1998

  46.   * @author      Mark Hapner

  47.   * @author      Rich Burridge

  48.   *

  49.   * @see TopicSession#createPublisher(Topic)

  50.   */

  51. 

  52. public interface TopicPublisher extends MessageProducer {

  53. 

  54.     /** Gets the topic associated with this <CODE>TopicPublisher</CODE>.

  55.       *

  56.       * @return this publisher's topic

  57.       *  

  58.       * @exception JMSException if the JMS provider fails to get the topic for

  59.       *                         this <CODE>TopicPublisher</CODE>

  60.       *                         due to some internal error.

  61.       */

  62. 

  63.     Topic 

  64.     getTopic() throws JMSException;

  65. 

  66.  

  67.     /** Publishes a message to the topic.

  68.       * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, priority,

  69.       * and time to live.

  70.       *

  71.       * @param message the message to publish

  72.       *

  73.       * @exception JMSException if the JMS provider fails to publish the message

  74.       *                         due to some internal error.

  75.       * @exception MessageFormatException if an invalid message is specified.

  76.       * @exception InvalidDestinationException if a client uses this method

  77.       *                         with a <CODE>TopicPublisher</CODE> with

  78.       *                         an invalid topic.

  79.       * @exception java.lang.UnsupportedOperationException if a client uses this

  80.       *                         method with a <CODE>TopicPublisher</CODE> that

  81.       *                         did not specify a topic at creation time.

  82.       * 

  83.       * @see javax.jms.MessageProducer#getDeliveryMode()

  84.       * @see javax.jms.MessageProducer#getTimeToLive()

  85.       * @see javax.jms.MessageProducer#getPriority()

  86.       */

  87. 

  88.     void 

  89.     publish(Message message) throws JMSException;

  90. 

  91. 

  92.     /** Publishes a message to the topic, specifying delivery mode,

  93.       * priority, and time to live.

  94.       *

  95.       * @param message the message to publish

  96.       * @param deliveryMode the delivery mode to use

  97.       * @param priority the priority for this message

  98.       * @param timeToLive the message's lifetime (in milliseconds)

  99.       *

  100.       * @exception JMSException if the JMS provider fails to publish the message

  101.       *                         due to some internal error.

  102.       * @exception MessageFormatException if an invalid message is specified.

  103.       * @exception InvalidDestinationException if a client uses this method

  104.       *                         with a <CODE>TopicPublisher</CODE> with

  105.       *                         an invalid topic.

  106.       * @exception java.lang.UnsupportedOperationException if a client uses this

  107.       *                         method with a <CODE>TopicPublisher</CODE> that

  108.       *                         did not specify a topic at creation time.

  109.       */

  110.  

  111.     void

  112.     publish(Message message, 

  113.             int deliveryMode, 

  114. 	    int priority,

  115. 	    long timeToLive) throws JMSException;

  116. 

  117. 

  118.     /** Publishes a message to a topic for an unidentified message producer. 

  119.       * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, 

  120.       * priority, and time to live.

  121.       *  

  122.       * <P>Typically, a message producer is assigned a topic at creation 

  123.       * time; however, the JMS API also supports unidentified message producers,

  124.       * which require that the topic be supplied every time a message is

  125.       * published.

  126.       *

  127.       * @param topic the topic to publish this message to

  128.       * @param message the message to publish

  129.       *  

  130.       * @exception JMSException if the JMS provider fails to publish the message

  131.       *                         due to some internal error.

  132.       * @exception MessageFormatException if an invalid message is specified.

  133.       * @exception InvalidDestinationException if a client uses

  134.       *                         this method with an invalid topic.

  135.       * 

  136.       * @see javax.jms.MessageProducer#getDeliveryMode()

  137.       * @see javax.jms.MessageProducer#getTimeToLive()

  138.       * @see javax.jms.MessageProducer#getPriority()

  139.       */ 

  140. 

  141.     void

  142.     publish(Topic topic, Message message) throws JMSException;

  143. 

  144. 

  145.     /** Publishes a message to a topic for an unidentified message 

  146.       * producer, specifying delivery mode, priority and time to live.

  147.       *  

  148.       * <P>Typically, a message producer is assigned a topic at creation

  149.       * time; however, the JMS API also supports unidentified message producers,

  150.       * which require that the topic be supplied every time a message is

  151.       * published.

  152.       *

  153.       * @param topic the topic to publish this message to

  154.       * @param message the message to publish

  155.       * @param deliveryMode the delivery mode to use

  156.       * @param priority the priority for this message

  157.       * @param timeToLive the message's lifetime (in milliseconds)

  158.       *  

  159.       * @exception JMSException if the JMS provider fails to publish the message

  160.       *                         due to some internal error.

  161.       * @exception MessageFormatException if an invalid message is specified.

  162.       * @exception InvalidDestinationException if a client uses

  163.       *                         this method with an invalid topic.

  164.       */ 

  165. 

  166.     void

  167.     publish(Topic topic, 

  168.             Message message, 

  169.             int deliveryMode, 

  170.             int priority,

  171. 	    long timeToLive) throws JMSException;

  172. }