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 <CODE>QueueSession</CODE> object provides methods for creating 
   25    * <CODE>QueueReceiver</CODE>, <CODE>QueueSender</CODE>, 
   26    * <CODE>QueueBrowser</CODE>, and <CODE>TemporaryQueue</CODE> objects.
   27    *
   28    * <P>If there are messages that have been received but not acknowledged 
   29    * when a <CODE>QueueSession</CODE> terminates, these messages will be retained 
   30    * and redelivered when a consumer next accesses the queue.
   31    *
   32    *<P>A <CODE>QueueSession</CODE> is used for creating Point-to-Point specific
   33    * objects. In general, use the <CODE>Session</CODE> object. 
   34    * The <CODE>QueueSession</CODE> is used to support
   35    * existing code. Using the <CODE>Session</CODE> object simplifies the 
   36    * programming model, and allows transactions to be used across the two 
   37    * messaging domains.
   38    * 
   39    * <P>A <CODE>QueueSession</CODE> cannot be used to create objects specific to the 
   40    * publish/subscribe domain. The following methods inherit from 
   41    * <CODE>Session</CODE>, but must throw an
   42    * <CODE>IllegalStateException</CODE> 
   43    * if they are used from <CODE>QueueSession</CODE>:
   44    *<UL>
   45    *   <LI><CODE>createDurableSubscriber</CODE>
   46    *   <LI><CODE>createTemporaryTopic</CODE>
   47    *   <LI><CODE>createTopic</CODE>
   48    *   <LI><CODE>unsubscribe</CODE>
   49    * </UL>
   50    *
   51    * @see         javax.jms.Session
   52    * @see         javax.jms.QueueConnection#createQueueSession(boolean, int)
   53    * @see         javax.jms.XAQueueSession#getQueueSession()
   54    */
   55   
   56   public interface QueueSession extends Session
   57   {
   58   
   59      /** Creates a queue identity given a <CODE>Queue</CODE> name.
   60       *
   61       * <P>This facility is provided for the rare cases where clients need to
   62       * dynamically manipulate queue identity. It allows the creation of a
   63       * queue identity with a provider-specific name. Clients that depend 
   64       * on this ability are not portable.
   65       *
   66       * <P>Note that this method is not for creating the physical queue. 
   67       * The physical creation of queues is an administrative task and is not
   68       * to be initiated by the JMS API. The one exception is the
   69       * creation of temporary queues, which is accomplished with the 
   70       * <CODE>createTemporaryQueue</CODE> method.
   71       *
   72       * @param queueName the name of this <CODE>Queue</CODE>
   73       *
   74       * @return a <CODE>Queue</CODE> with the given name
   75       *
   76       * @exception JMSException if the session fails to create a queue
   77       *                         due to some internal error.
   78       */
   79   
   80      Queue createQueue(String queueName) throws JMSException;
   81   
   82      /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from the
   83       * specified queue.
   84       *
   85       * @param queue the <CODE>Queue</CODE> to access
   86       *
   87       * @exception JMSException if the session fails to create a receiver
   88       *                         due to some internal error.
   89       * @exception InvalidDestinationException if an invalid queue is specified.
   90       */
   91   
   92      QueueReceiver createReceiver(Queue queue) throws JMSException;
   93   
   94      /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from the 
   95       * specified queue using a message selector.
   96       *  
   97       * @param queue the <CODE>Queue</CODE> to access
   98       * @param messageSelector only messages with properties matching the
   99       * message selector expression are delivered. A value of null or
  100       * an empty string indicates that there is no message selector 
  101       * for the message consumer.
  102       *  
  103       * @exception JMSException if the session fails to create a receiver
  104       *                         due to some internal error.
  105       * @exception InvalidDestinationException if an invalid queue is specified.
  106       * @exception InvalidSelectorException if the message selector is invalid.
  107       *
  108       */
  109   
  110      QueueReceiver createReceiver(Queue queue, String messageSelector) throws JMSException;
  111   
  112      /** Creates a <CODE>QueueSender</CODE> object to send messages to the 
  113       * specified queue.
  114       *
  115       * @param queue the <CODE>Queue</CODE> to access, or null if this is an 
  116       * unidentified producer
  117       *
  118       * @exception JMSException if the session fails to create a sender
  119       *                         due to some internal error.
  120       * @exception InvalidDestinationException if an invalid queue is specified.
  121       */
  122   
  123      QueueSender createSender(Queue queue) throws JMSException;
  124   
  125      /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on 
  126       * the specified queue.
  127       *
  128       * @param queue the <CODE>Queue</CODE> to access
  129       *
  130       * @exception JMSException if the session fails to create a browser
  131       *                         due to some internal error.
  132       * @exception InvalidDestinationException if an invalid queue is specified.
  133       */
  134   
  135      QueueBrowser createBrowser(Queue queue) throws JMSException;
  136   
  137      /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on 
  138       * the specified queue using a message selector.
  139       *  
  140       * @param queue the <CODE>Queue</CODE> to access
  141       * @param messageSelector only messages with properties matching the
  142       * message selector expression are delivered. A value of null or
  143       * an empty string indicates that there is no message selector 
  144       * for the message consumer.
  145       *  
  146       * @exception JMSException if the session fails to create a browser
  147       *                         due to some internal error.
  148       * @exception InvalidDestinationException if an invalid queue is specified.
  149       * @exception InvalidSelectorException if the message selector is invalid.
  150       */
  151   
  152      QueueBrowser createBrowser(Queue queue, String messageSelector) throws JMSException;
  153   
  154      /** Creates a <CODE>TemporaryQueue</CODE> object. Its lifetime will be that 
  155       * of the <CODE>QueueConnection</CODE> unless it is deleted earlier.
  156       *
  157       * @return a temporary queue identity
  158       *
  159       * @exception JMSException if the session fails to create a temporary queue
  160       *                         due to some internal error.
  161       */
  162   
  163      TemporaryQueue createTemporaryQueue() throws JMSException;
  164   }

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