Home » jboss-javaee-sources » javax » jms » [javadoc | source]

    1   /*
    2    * JBoss, Home of Professional Open Source
    3    * Copyright 2005, JBoss Inc., and individual contributors as indicated
    4    * by the @authors tag. See the copyright.txt in the distribution for a
    5    * full listing of individual contributors.
    6    *
    7    * This is free software; you can redistribute it and/or modify it
    8    * under the terms of the GNU Lesser General Public License as
    9    * published by the Free Software Foundation; either version 2.1 of
   10    * the License, or (at your option) any later version.
   11    *
   12    * This software is distributed in the hope that it will be useful,
   13    * but WITHOUT ANY WARRANTY; without even the implied warranty of
   14    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
   15    * Lesser General Public License for more details.
   16    *
   17    * You should have received a copy of the GNU Lesser General Public
   18    * License along with this software; if not, write to the Free
   19    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
   20    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
   21    */
   22   package javax.jms;
   23   
   24   /** A client uses a <CODE>QueueSender</CODE> object to send messages to a queue.
   25    * 
   26    * <P>Normally, the <CODE>Queue</CODE> is specified when a 
   27    * <CODE>QueueSender</CODE> is created.  In this case, an attempt to use
   28    * the <CODE>send</CODE> methods for an unidentified 
   29    * <CODE>QueueSender</CODE> will throw a 
   30    * <CODE>java.lang.UnsupportedOperationException</CODE>.
   31    * 
   32    * <P>If the <CODE>QueueSender</CODE> is created with an unidentified 
   33    * <CODE>Queue</CODE>, an attempt to use the <CODE>send</CODE> methods that 
   34    * assume that the <CODE>Queue</CODE> has been identified will throw a
   35    * <CODE>java.lang.UnsupportedOperationException</CODE>.
   36    *
   37    * <P>During the execution of its <CODE>send</CODE> method, a message 
   38    * must not be changed by other threads within the client. 
   39    * If the message is modified, the result of the <CODE>send</CODE> is 
   40    * undefined.
   41    * 
   42    * <P>After sending a message, a client may retain and modify it
   43    * without affecting the message that has been sent. The same message
   44    * object may be sent multiple times.
   45    * 
   46    * <P>The following message headers are set as part of sending a 
   47    * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>, 
   48    * <code>JMSExpiration</code>, <code>JMSPriority</code>, 
   49    * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
   50    * When the message is sent, the values of these headers are ignored. 
   51    * After the completion of the <CODE>send</CODE>, the headers hold the values 
   52    * specified by the method sending the message. It is possible for the 
   53    * <code>send</code> method not to set <code>JMSMessageID</code> and 
   54    * <code>JMSTimeStamp</code> if the 
   55    * setting of these headers is explicitly disabled by the 
   56    * <code>MessageProducer.setDisableMessageID</code> or
   57    * <code>MessageProducer.setDisableMessageTimestamp</code> method.
   58    *
   59    * <P>Creating a <CODE>MessageProducer</CODE> provides the same features as
   60    * creating a <CODE>QueueSender</CODE>. A <CODE>MessageProducer</CODE> object is 
   61    * recommended when creating new code. The  <CODE>QueueSender</CODE> is
   62    * provided to support existing code.
   63    *
   64    * @see         javax.jms.MessageProducer
   65    * @see         javax.jms.Session#createProducer(Destination)
   66    * @see         javax.jms.QueueSession#createSender(Queue)
   67    */
   68   
   69   public interface QueueSender extends MessageProducer
   70   {
   71   
   72      /** Gets the queue associated with this <CODE>QueueSender</CODE>.
   73       *  
   74       * @return this sender's queue 
   75       *  
   76       * @exception JMSException if the JMS provider fails to get the queue for
   77       *                         this <CODE>QueueSender</CODE>
   78       *                         due to some internal error.
   79       */
   80   
   81      Queue getQueue() throws JMSException;
   82   
   83      /** Sends a message to the queue. Uses the <CODE>QueueSender</CODE>'s 
   84       * default delivery mode, priority, and time to live.
   85       *
   86       * @param message the message to send 
   87       *  
   88       * @exception JMSException if the JMS provider fails to send the message 
   89       *                         due to some internal error.
   90       * @exception MessageFormatException if an invalid message is specified.
   91       * @exception InvalidDestinationException if a client uses
   92       *                         this method with a <CODE>QueueSender</CODE> with
   93       *                         an invalid queue.
   94       * @exception java.lang.UnsupportedOperationException if a client uses this
   95       *                         method with a <CODE>QueueSender</CODE> that did
   96       *                         not specify a queue at creation time.
   97       * 
   98       * @see javax.jms.MessageProducer#getDeliveryMode()
   99       * @see javax.jms.MessageProducer#getTimeToLive()
  100       * @see javax.jms.MessageProducer#getPriority()
  101       */
  102   
  103      void send(Message message) throws JMSException;
  104   
  105      /** Sends a message to the queue, specifying delivery mode, priority, and 
  106       * time to live.
  107       *
  108       * @param message the message to send
  109       * @param deliveryMode the delivery mode to use
  110       * @param priority the priority for this message
  111       * @param timeToLive the message's lifetime (in milliseconds)
  112       *  
  113       * @exception JMSException if the JMS provider fails to send the message 
  114       *                         due to some internal error.
  115       * @exception MessageFormatException if an invalid message is specified.
  116       * @exception InvalidDestinationException if a client uses
  117       *                         this method with a <CODE>QueueSender</CODE> with
  118       *                         an invalid queue.
  119       * @exception java.lang.UnsupportedOperationException if a client uses this
  120       *                         method with a <CODE>QueueSender</CODE> that did
  121       *                         not specify a queue at creation time.
  122       */
  123   
  124      void send(Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
  125   
  126      /** Sends a message to a queue for an unidentified message producer.
  127       * Uses the <CODE>QueueSender</CODE>'s default delivery mode, priority,
  128       * and time to live.
  129       *
  130       * <P>Typically, a message producer is assigned a queue at creation 
  131       * time; however, the JMS API also supports unidentified message producers,
  132       * which require that the queue be supplied every time a message is
  133       * sent.
  134       *  
  135       * @param queue the queue to send this message to
  136       * @param message the message to send
  137       *  
  138       * @exception JMSException if the JMS provider fails to send the message 
  139       *                         due to some internal error.
  140       * @exception MessageFormatException if an invalid message is specified.
  141       * @exception InvalidDestinationException if a client uses
  142       *                         this method with an invalid queue.
  143       * 
  144       * @see javax.jms.MessageProducer#getDeliveryMode()
  145       * @see javax.jms.MessageProducer#getTimeToLive()
  146       * @see javax.jms.MessageProducer#getPriority()
  147       */
  148   
  149      void send(Queue queue, Message message) throws JMSException;
  150   
  151      /** Sends a message to a queue for an unidentified message producer, 
  152       * specifying delivery mode, priority and time to live.
  153       *  
  154       * <P>Typically, a message producer is assigned a queue at creation 
  155       * time; however, the JMS API also supports unidentified message producers,
  156       * which require that the queue be supplied every time a message is
  157       * sent.
  158       *  
  159       * @param queue the queue to send this message to
  160       * @param message the message to send
  161       * @param deliveryMode the delivery mode to use
  162       * @param priority the priority for this message
  163       * @param timeToLive the message's lifetime (in milliseconds)
  164       *  
  165       * @exception JMSException if the JMS provider fails to send the message 
  166       *                         due to some internal error.
  167       * @exception MessageFormatException if an invalid message is specified.
  168       * @exception InvalidDestinationException if a client uses
  169       *                         this method with an invalid queue.
  170       */
  171   
  172      void send(Queue queue, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
  173   }

Home » jboss-javaee-sources » javax » jms » [javadoc | source]