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 <CODE>TopicSession</CODE> object provides methods for creating 

  9.   * <CODE>TopicPublisher</CODE>, <CODE>TopicSubscriber</CODE>, and 

  10.   * <CODE>TemporaryTopic</CODE> objects. It also provides a method for 

  11.   * deleting its client's durable subscribers.

  12.   *

  13.   * @version     1.0 - 4 August 1998

  14.   * @author      Mark Hapner

  15.   * @author      Rich Burridge

  16.   *

  17.   * @see         javax.jms.Session

  18.   * @see	 javax.jms.TopicConnection#createTopicSession(boolean, int)

  19.   * @see         javax.jms.XATopicSession#getTopicSession()

  20.   */

  21. 

  22. public interface TopicSession extends Session {

  23. 

  24.     /** Creates a topic identity given a <CODE>Topic</CODE> name.

  25.       *

  26.       * <P>This facility is provided for the rare cases where clients need to

  27.       * dynamically manipulate topic identity. This allows the creation of a

  28.       * topic identity with a provider-specific name. Clients that depend 

  29.       * on this ability are not portable.

  30.       *

  31.       * <P>Note that this method is not for creating the physical topic. 

  32.       * The physical creation of topics is an administrative task and is not

  33.       * to be initiated by the JMS API. The one exception is the

  34.       * creation of temporary topics, which is accomplished with the 

  35.       * <CODE>createTemporaryTopic</CODE> method.

  36.       *  

  37.       * @param topicName the name of this <CODE>Topic</CODE>

  38.       *

  39.       * @return a <CODE>Topic</CODE> with the given name

  40.       *

  41.       * @exception JMSException if the session fails to create a topic

  42.       *                         due to some internal error.

  43.       */

  44. 

  45.     Topic

  46.     createTopic(String topicName) throws JMSException;

  47. 

  48. 

  49.     /** Creates a nondurable subscriber to the specified topic.

  50.       *  

  51.       * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive 

  52.       * messages that have been published to a topic.

  53.       *

  54.       * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable. 

  55.       * They receive only messages that are published while they are active.

  56.       *

  57.       * <P>In some cases, a connection may both publish and subscribe to a 

  58.       * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber

  59.       * to inhibit the delivery of messages published by its own connection.

  60.       * The default value for this attribute is false.

  61.       *

  62.       * @param topic the <CODE>Topic</CODE> to subscribe to

  63.       *  

  64.       * @exception JMSException if the session fails to create a subscriber

  65.       *                         due to some internal error.

  66.       * @exception InvalidDestinationException if an invalid topic is specified.

  67.       */ 

  68. 

  69.     TopicSubscriber

  70.     createSubscriber(Topic topic) throws JMSException;

  71. 

  72. 

  73.     /** Creates a nondurable subscriber to the specified topic, using a

  74.       * message selector or specifying whether messages published by its

  75.       * own connection should be delivered to it.

  76.       *

  77.       * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive 

  78.       * messages that have been published to a topic.

  79.       *  

  80.       * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable. 

  81.       * They receive only messages that are published while they are active.

  82.       *

  83.       * <P>Messages filtered out by a subscriber's message selector will 

  84.       * never be delivered to the subscriber. From the subscriber's 

  85.       * perspective, they do not exist.

  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.       * @param messageSelector only messages with properties matching the

  94.       * message selector expression are delivered. A value of null or

  95.       * an empty string indicates that there is no message selector 

  96.       * for the message consumer.

  97.       * @param noLocal if set, inhibits the delivery of messages published

  98.       * by its own connection

  99.       * 

  100.       * @exception JMSException if the session fails to create a subscriber

  101.       *                         due to some internal error.

  102.       * @exception InvalidDestinationException if an invalid topic is specified.

  103.       * @exception InvalidSelectorException if the message selector is invalid.

  104.       */

  105. 

  106.     TopicSubscriber 

  107.     createSubscriber(Topic topic, 

  108. 		     String messageSelector,

  109. 		     boolean noLocal) throws JMSException;

  110. 

  111. 

  112.     /** Creates a durable subscriber to the specified topic.

  113.       *  

  114.       * <P>If a client needs to receive all the messages published on a 

  115.       * topic, including the ones published while the subscriber is inactive,

  116.       * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider

  117.       * retains a record of this 

  118.       * durable subscription and insures that all messages from the topic's 

  119.       * publishers are retained until they are acknowledged by this 

  120.       * durable subscriber or they have expired.

  121.       *

  122.       * <P>Sessions with durable subscribers must always provide the same 

  123.       * client identifier. In addition, each client must specify a name that 

  124.       * uniquely identifies (within client identifier) each durable 

  125.       * subscription it creates. Only one session at a time can have a 

  126.       * <CODE>TopicSubscriber</CODE> for a particular durable subscription.

  127.       *

  128.       * <P>A client can change an existing durable subscription by creating 

  129.       * a durable <CODE>TopicSubscriber</CODE> with the same name and a new 

  130.       * topic and/or 

  131.       * message selector. Changing a durable subscriber is equivalent to 

  132.       * unsubscribing (deleting) the old one and creating a new one.

  133.       *

  134.       * <P>In some cases, a connection may both publish and subscribe to a 

  135.       * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber

  136.       * to inhibit the delivery of messages published by its own connection.

  137.       * The default value for this attribute is false.

  138.       *

  139.       * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to

  140.       * @param name the name used to identify this subscription

  141.       *  

  142.       * @exception JMSException if the session fails to create a subscriber

  143.       *                         due to some internal error.

  144.       * @exception InvalidDestinationException if an invalid topic is specified.

  145.       */ 

  146. 

  147.     TopicSubscriber

  148.     createDurableSubscriber(Topic topic, 

  149. 			    String name) throws JMSException;

  150. 

  151. 

  152.     /** Creates a durable subscriber to the specified topic, using a

  153.       * message selector or specifying whether messages published by its

  154.       * own connection should be delivered to it.

  155.       *  

  156.       * <P>If a client needs to receive all the messages published on a 

  157.       * topic, including the ones published while the subscriber is inactive,

  158.       * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider

  159.       * retains a record of this 

  160.       * durable subscription and insures that all messages from the topic's 

  161.       * publishers are retained until they are acknowledged by this 

  162.       * durable subscriber or they have expired.

  163.       *

  164.       * <P>Sessions with durable subscribers must always provide the same

  165.       * client identifier. In addition, each client must specify a name which

  166.       * uniquely identifies (within client identifier) each durable

  167.       * subscription it creates. Only one session at a time can have a

  168.       * <CODE>TopicSubscriber</CODE> for a particular durable subscription.

  169.       * An inactive durable subscriber is one that exists but

  170.       * does not currently have a message consumer associated with it.

  171.       *

  172.       * <P>A client can change an existing durable subscription by creating 

  173.       * a durable <CODE>TopicSubscriber</CODE> with the same name and a new 

  174.       * topic and/or 

  175.       * message selector. Changing a durable subscriber is equivalent to 

  176.       * unsubscribing (deleting) the old one and creating a new one.

  177.       *

  178.       * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to

  179.       * @param name the name used to identify this subscription

  180.       * @param messageSelector only messages with properties matching the

  181.       * message selector expression are delivered.  A value of null or

  182.       * an empty string indicates that there is no message selector 

  183.       * for the message consumer.

  184.       * @param noLocal if set, inhibits the delivery of messages published

  185.       * by its own connection

  186.       *  

  187.       * @exception JMSException if the session fails to create a subscriber

  188.       *                         due to some internal error.

  189.       * @exception InvalidDestinationException if an invalid topic is specified.

  190.       * @exception InvalidSelectorException if the message selector is invalid.

  191.       */ 

  192.  

  193.     TopicSubscriber

  194.     createDurableSubscriber(Topic topic,

  195.                             String name, 

  196. 			    String messageSelector,

  197. 			    boolean noLocal) throws JMSException;

  198. 

  199. 

  200.     /** Creates a publisher for the specified topic.

  201.       *

  202.       * <P>A client uses a <CODE>TopicPublisher</CODE> object to publish 

  203.       * messages on a topic.

  204.       * Each time a client creates a <CODE>TopicPublisher</CODE> on a topic, it

  205.       * defines a 

  206.       * new sequence of messages that have no ordering relationship with the 

  207.       * messages it has previously sent.

  208.       *

  209.       * @param topic the <CODE>Topic</CODE> to publish to, or null if this is an

  210.       * unidentified producer

  211.       *

  212.       * @exception JMSException if the session fails to create a publisher

  213.       *                         due to some internal error.

  214.       * @exception InvalidDestinationException if an invalid topic is specified.

  215.      */

  216. 

  217.     TopicPublisher 

  218.     createPublisher(Topic topic) throws JMSException;

  219. 

  220. 

  221.     /** Creates a <CODE>TemporaryTopic</CODE> object. Its lifetime will be that 

  222.       * of the <CODE>TopicConnection</CODE> unless it is deleted earlier.

  223.       *

  224.       * @return a temporary topic identity

  225.       *

  226.       * @exception JMSException if the session fails to create a temporary

  227.       *                         topic due to some internal error.

  228.       */

  229.  

  230.     TemporaryTopic

  231.     createTemporaryTopic() throws JMSException;

  232. 

  233. 

  234.     /** Unsubscribes a durable subscription that has been created by a client.

  235.       *  

  236.       * <P>This method deletes the state being maintained on behalf of the 

  237.       * subscriber by its provider.

  238.       *

  239.       * <P>It is erroneous for a client to delete a durable subscription

  240.       * while there is an active <CODE>TopicSubscriber</CODE> for the 

  241.       * subscription, or while a consumed message is part of a pending 

  242.       * transaction or has not been acknowledged in the session.

  243.       *

  244.       * @param name the name used to identify this subscription

  245.       *  

  246.       * @exception JMSException if the session fails to unsubscribe to the 

  247.       *                         durable subscription due to some internal error.

  248.       * @exception InvalidDestinationException if an invalid subscription name

  249.       *                                        is specified.

  250.       */

  251. 

  252.     void

  253.     unsubscribe(String name) throws JMSException;

  254. }