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>QueueSender</CODE> object to send messages to a queue.

  9.   * 

  10.   * <P>Normally, the <CODE>Queue</CODE> is specified when a 

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

  12.   * the <CODE>send</CODE> methods for an unidentified 

  13.   * <CODE>QueueSender</CODE> will throw a 

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

  15.   * 

  16.   * <P>If the <CODE>QueueSender</CODE> is created with an unidentified 

  17.   * <CODE>Queue</CODE>, an attempt to use the <CODE>send</CODE> methods that 

  18.   * assume that the <CODE>Queue</CODE> has been identified will throw a

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

  20.   *

  21.   * <P>During the execution of its <CODE>send</CODE> method, a message 

  22.   * must not be changed by other threads within the client. 

  23.   * If the message is modified, the result of the <CODE>send</CODE> is 

  24.   * undefined.

  25.   * 

  26.   * <P>After sending a message, a client may retain and modify it

  27.   * without affecting the message that has been sent. The same message

  28.   * object may be sent multiple times.

  29.   * 

  30.   * <P>The following message headers are set as part of sending a 

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

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

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

  34.   * When the message is sent, the values of these headers are ignored. 

  35.   * After the completion of the <CODE>send</CODE>, the headers hold the values 

  36.   * specified by the method sending the message. It is possible for the 

  37.   * <code>send</code> method not to set <code>JMSMessageID</code> and 

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

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

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

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

  42.   *

  43.   * @version     1.0 - 4 August 1998

  44.   * @author      Mark Hapner

  45.   * @author      Rich Burridge

  46.   *

  47.   * @see         javax.jms.MessageProducer

  48.   * @see         javax.jms.QueueSession#createSender(Queue)

  49.   */

  50. 

  51. public interface QueueSender extends MessageProducer {

  52. 

  53.     /** Gets the queue associated with this <CODE>QueueSender</CODE>.

  54.       *  

  55.       * @return this sender's queue 

  56.       *  

  57.       * @exception JMSException if the JMS provider fails to get the queue for

  58.       *                         this <CODE>QueueSender</CODE>

  59.       *                         due to some internal error.

  60.       */ 

  61.  

  62.     Queue

  63.     getQueue() throws JMSException;

  64. 

  65. 

  66.     /** Sends a message to the queue. Uses the <CODE>QueueSender</CODE>'s 

  67.       * default delivery mode, priority, and time to live.

  68.       *

  69.       * @param message the message to send 

  70.       *  

  71.       * @exception JMSException if the JMS provider fails to send the message 

  72.       *                         due to some internal error.

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

  74.       * @exception InvalidDestinationException if a client uses

  75.       *                         this method with a <CODE>QueueSender</CODE> with

  76.       *                         an invalid queue.

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

  78.       *                         method with a <CODE>QueueSender</CODE> that did

  79.       *                         not specify a queue at creation time.

  80.       * 

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

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

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

  84.       */

  85. 

  86.     void 

  87.     send(Message message) throws JMSException;

  88. 

  89. 

  90.     /** Sends a message to the queue, specifying delivery mode, priority, and 

  91.       * time to live.

  92.       *

  93.       * @param message the message to send

  94.       * @param deliveryMode the delivery mode to use

  95.       * @param priority the priority for this message

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

  97.       *  

  98.       * @exception JMSException if the JMS provider fails to send the message 

  99.       *                         due to some internal error.

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

  101.       * @exception InvalidDestinationException if a client uses

  102.       *                         this method with a <CODE>QueueSender</CODE> with

  103.       *                         an invalid queue.

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

  105.       *                         method with a <CODE>QueueSender</CODE> that did

  106.       *                         not specify a queue at creation time.

  107.       */

  108. 

  109.     void 

  110.     send(Message message, 

  111. 	 int deliveryMode, 

  112. 	 int priority,

  113. 	 long timeToLive) throws JMSException;

  114. 

  115. 

  116.     /** Sends a message to a queue for an unidentified message producer.

  117.       * Uses the <CODE>QueueSender</CODE>'s default delivery mode, priority,

  118.       * and time to live.

  119.       *

  120.       * <P>Typically, a message producer is assigned a queue at creation 

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

  122.       * which require that the queue be supplied every time a message is

  123.       * sent.

  124.       *  

  125.       * @param queue the queue to send this message to

  126.       * @param message the message to send

  127.       *  

  128.       * @exception JMSException if the JMS provider fails to send the message 

  129.       *                         due to some internal error.

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

  131.       * @exception InvalidDestinationException if a client uses

  132.       *                         this method with an invalid queue.

  133.       * 

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

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

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

  137.       */ 

  138.  

  139.     void

  140.     send(Queue queue, Message message) throws JMSException;

  141.  

  142.  

  143.     /** Sends a message to a queue for an unidentified message producer, 

  144.       * specifying delivery mode, priority and time to live.

  145.       *  

  146.       * <P>Typically, a message producer is assigned a queue at creation 

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

  148.       * which require that the queue be supplied every time a message is

  149.       * sent.

  150.       *  

  151.       * @param queue the queue to send this message to

  152.       * @param message the message to send

  153.       * @param deliveryMode the delivery mode to use

  154.       * @param priority the priority for this message

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

  156.       *  

  157.       * @exception JMSException if the JMS provider fails to send the message 

  158.       *                         due to some internal error.

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

  160.       * @exception InvalidDestinationException if a client uses

  161.       *                         this method with an invalid queue.

  162.       */ 

  163. 

  164.     void

  165.     send(Queue queue, 

  166. 	 Message message, 

  167. 	 int deliveryMode, 

  168. 	 int priority,

  169. 	 long timeToLive) throws JMSException;

  170. }