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>TopicSession</CODE> object provides methods for creating 
   25    * <CODE>TopicPublisher</CODE>, <CODE>TopicSubscriber</CODE>, and 
   26    * <CODE>TemporaryTopic</CODE> objects. It also provides a method for 
   27    * deleting its client's durable subscribers.
   28    *
   29    *<P>A <CODE>TopicSession</CODE> is used for creating Pub/Sub specific
   30    * objects. In general, use the  <CODE>Session</CODE> object, and 
   31    *  use <CODE>TopicSession</CODE>  only to support
   32    * existing code. Using the <CODE>Session</CODE> object simplifies the 
   33    * programming model, and allows transactions to be used across the two 
   34    * messaging domains.
   35    * 
   36    * <P>A <CODE>TopicSession</CODE> cannot be used to create objects specific to the 
   37    * point-to-point domain. The following methods inherit from 
   38    * <CODE>Session</CODE>, but must throw an 
   39    * <CODE>IllegalStateException</CODE> 
   40    * if used from <CODE>TopicSession</CODE>:
   41    *<UL>
   42    *   <LI><CODE>createBrowser</CODE>
   43    *   <LI><CODE>createQueue</CODE>
   44    *   <LI><CODE>createTemporaryQueue</CODE>
   45    *</UL>
   46    *
   47    * @see         javax.jms.Session
   48    * @see	 javax.jms.Connection#createSession(boolean, int)
   49    * @see	 javax.jms.TopicConnection#createTopicSession(boolean, int)
   50    * @see         javax.jms.XATopicSession#getTopicSession()
   51    */
   52   
   53   public interface TopicSession extends Session
   54   {
   55   
   56      /** Creates a topic identity given a <CODE>Topic</CODE> name.
   57       *
   58       * <P>This facility is provided for the rare cases where clients need to
   59       * dynamically manipulate topic identity. This allows the creation of a
   60       * topic identity with a provider-specific name. Clients that depend 
   61       * on this ability are not portable.
   62       *
   63       * <P>Note that this method is not for creating the physical topic. 
   64       * The physical creation of topics is an administrative task and is not
   65       * to be initiated by the JMS API. The one exception is the
   66       * creation of temporary topics, which is accomplished with the 
   67       * <CODE>createTemporaryTopic</CODE> method.
   68       *  
   69       * @param topicName the name of this <CODE>Topic</CODE>
   70       *
   71       * @return a <CODE>Topic</CODE> with the given name
   72       *
   73       * @exception JMSException if the session fails to create a topic
   74       *                         due to some internal error.
   75       */
   76   
   77      Topic createTopic(String topicName) throws JMSException;
   78   
   79      /** Creates a nondurable subscriber to the specified topic.
   80       *  
   81       * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive 
   82       * messages that have been published to a topic.
   83       *
   84       * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable. 
   85       * They receive only messages that are published while they are active.
   86       *
   87       * <P>In some cases, a connection may both publish and subscribe to a 
   88       * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
   89       * to inhibit the delivery of messages published by its own connection.
   90       * The default value for this attribute is false.
   91       *
   92       * @param topic the <CODE>Topic</CODE> to subscribe to
   93       *  
   94       * @exception JMSException if the session fails to create a subscriber
   95       *                         due to some internal error.
   96       * @exception InvalidDestinationException if an invalid topic is specified.
   97       */
   98   
   99      TopicSubscriber createSubscriber(Topic topic) throws JMSException;
  100   
  101      /** Creates a nondurable subscriber to the specified topic, using a
  102       * message selector or specifying whether messages published by its
  103       * own connection should be delivered to it.
  104       *
  105       * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive 
  106       * messages that have been published to a topic.
  107       *  
  108       * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable. 
  109       * They receive only messages that are published while they are active.
  110       *
  111       * <P>Messages filtered out by a subscriber's message selector will 
  112       * never be delivered to the subscriber. From the subscriber's 
  113       * perspective, they do not exist.
  114       *
  115       * <P>In some cases, a connection may both publish and subscribe to a 
  116       * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
  117       * to inhibit the delivery of messages published by its own connection.
  118       * The default value for this attribute is false.
  119       *
  120       * @param topic the <CODE>Topic</CODE> to subscribe to
  121       * @param messageSelector only messages with properties matching the
  122       * message selector expression are delivered. A value of null or
  123       * an empty string indicates that there is no message selector 
  124       * for the message consumer.
  125       * @param noLocal if set, inhibits the delivery of messages published
  126       * by its own connection
  127       * 
  128       * @exception JMSException if the session fails to create a subscriber
  129       *                         due to some internal error.
  130       * @exception InvalidDestinationException if an invalid topic is specified.
  131       * @exception InvalidSelectorException if the message selector is invalid.
  132       */
  133   
  134      TopicSubscriber createSubscriber(Topic topic, String messageSelector, boolean noLocal) throws JMSException;
  135   
  136      /** Creates a durable subscriber to the specified topic.
  137       *  
  138       * <P>If a client needs to receive all the messages published on a 
  139       * topic, including the ones published while the subscriber is inactive,
  140       * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
  141       * retains a record of this 
  142       * durable subscription and insures that all messages from the topic's 
  143       * publishers are retained until they are acknowledged by this 
  144       * durable subscriber or they have expired.
  145       *
  146       * <P>Sessions with durable subscribers must always provide the same 
  147       * client identifier. In addition, each client must specify a name that 
  148       * uniquely identifies (within client identifier) each durable 
  149       * subscription it creates. Only one session at a time can have a 
  150       * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
  151       *
  152       * <P>A client can change an existing durable subscription by creating 
  153       * a durable <CODE>TopicSubscriber</CODE> with the same name and a new 
  154       * topic and/or 
  155       * message selector. Changing a durable subscriber is equivalent to 
  156       * unsubscribing (deleting) the old one and creating a new one.
  157       *
  158       * <P>In some cases, a connection may both publish and subscribe to a 
  159       * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
  160       * to inhibit the delivery of messages published by its own connection.
  161       * The default value for this attribute is false.
  162       *
  163       * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
  164       * @param name the name used to identify this subscription
  165       *  
  166       * @exception JMSException if the session fails to create a subscriber
  167       *                         due to some internal error.
  168       * @exception InvalidDestinationException if an invalid topic is specified.
  169       */
  170   
  171      TopicSubscriber createDurableSubscriber(Topic topic, String name) throws JMSException;
  172   
  173      /** Creates a durable subscriber to the specified topic, using a
  174       * message selector or specifying whether messages published by its
  175       * own connection should be delivered to it.
  176       *  
  177       * <P>If a client needs to receive all the messages published on a 
  178       * topic, including the ones published while the subscriber is inactive,
  179       * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
  180       * retains a record of this 
  181       * durable subscription and insures that all messages from the topic's 
  182       * publishers are retained until they are acknowledged by this 
  183       * durable subscriber or they have expired.
  184       *
  185       * <P>Sessions with durable subscribers must always provide the same
  186       * client identifier. In addition, each client must specify a name which
  187       * uniquely identifies (within client identifier) each durable
  188       * subscription it creates. Only one session at a time can have a
  189       * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
  190       * An inactive durable subscriber is one that exists but
  191       * does not currently have a message consumer associated with it.
  192       *
  193       * <P>A client can change an existing durable subscription by creating 
  194       * a durable <CODE>TopicSubscriber</CODE> with the same name and a new 
  195       * topic and/or 
  196       * message selector. Changing a durable subscriber is equivalent to 
  197       * unsubscribing (deleting) the old one and creating a new one.
  198       *
  199       * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
  200       * @param name the name used to identify this subscription
  201       * @param messageSelector only messages with properties matching the
  202       * message selector expression are delivered.  A value of null or
  203       * an empty string indicates that there is no message selector 
  204       * for the message consumer.
  205       * @param noLocal if set, inhibits the delivery of messages published
  206       * by its own connection
  207       *  
  208       * @exception JMSException if the session fails to create a subscriber
  209       *                         due to some internal error.
  210       * @exception InvalidDestinationException if an invalid topic is specified.
  211       * @exception InvalidSelectorException if the message selector is invalid.
  212       */
  213   
  214      TopicSubscriber createDurableSubscriber(Topic topic, String name, String messageSelector, boolean noLocal)
  215            throws JMSException;
  216   
  217      /** Creates a publisher for the specified topic.
  218       *
  219       * <P>A client uses a <CODE>TopicPublisher</CODE> object to publish 
  220       * messages on a topic.
  221       * Each time a client creates a <CODE>TopicPublisher</CODE> on a topic, it
  222       * defines a 
  223       * new sequence of messages that have no ordering relationship with the 
  224       * messages it has previously sent.
  225       *
  226       * @param topic the <CODE>Topic</CODE> to publish to, or null if this is an
  227       * unidentified producer
  228       *
  229       * @exception JMSException if the session fails to create a publisher
  230       *                         due to some internal error.
  231       * @exception InvalidDestinationException if an invalid topic is specified.
  232       */
  233   
  234      TopicPublisher createPublisher(Topic topic) throws JMSException;
  235   
  236      /** Creates a <CODE>TemporaryTopic</CODE> object. Its lifetime will be that 
  237       * of the <CODE>TopicConnection</CODE> unless it is deleted earlier.
  238       *
  239       * @return a temporary topic identity
  240       *
  241       * @exception JMSException if the session fails to create a temporary
  242       *                         topic due to some internal error.
  243       */
  244   
  245      TemporaryTopic createTemporaryTopic() throws JMSException;
  246   
  247      /** Unsubscribes a durable subscription that has been created by a client.
  248       *  
  249       * <P>This method deletes the state being maintained on behalf of the 
  250       * subscriber by its provider.
  251       *
  252       * <P>It is erroneous for a client to delete a durable subscription
  253       * while there is an active <CODE>TopicSubscriber</CODE> for the 
  254       * subscription, or while a consumed message is part of a pending 
  255       * transaction or has not been acknowledged in the session.
  256       *
  257       * @param name the name used to identify this subscription
  258       *  
  259       * @exception JMSException if the session fails to unsubscribe to the 
  260       *                         durable subscription due to some internal error.
  261       * @exception InvalidDestinationException if an invalid subscription name
  262       *                                        is specified.
  263       */
  264   
  265      void unsubscribe(String name) throws JMSException;
  266   }

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