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>TopicConnection</CODE> object is an active connection to a 

  9.   * publish/subscribe JMS provider. A client uses a <CODE>TopicConnection</CODE> 

  10.   * object to create one or more <CODE>TopicSession</CODE> objects

  11.   * for producing and consuming messages.

  12.   *

  13.   * @version     1.0 - 13 March 1998

  14.   * @author      Mark Hapner

  15.   * @author      Rich Burridge

  16.   *

  17.   * @see         javax.jms.Connection

  18.   * @see	 javax.jms.TopicConnectionFactory

  19.   */

  20. 

  21. public interface TopicConnection extends Connection {

  22. 

  23.     /** Creates a <CODE>TopicSession</CODE> object.

  24.       *

  25.       * @param transacted indicates whether the session is transacted

  26.       * @param acknowledgeMode indicates whether the consumer or the

  27.       * client will acknowledge any messages it receives; ignored if the session

  28.       * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>, 

  29.       * <code>Session.CLIENT_ACKNOWLEDGE</code>, and 

  30.       * <code>Session.DUPS_OK_ACKNOWLEDGE</code>. 

  31.       *  

  32.       * @return a newly created topic session

  33.       *  

  34.       * @exception JMSException if the <CODE>TopicConnection</CODE> object fails

  35.       *                         to create a session due to some internal error or

  36.       *                         lack of support for the specific transaction

  37.       *                         and acknowledgement mode.

  38.       *

  39.       * @see Session#AUTO_ACKNOWLEDGE 

  40.       * @see Session#CLIENT_ACKNOWLEDGE 

  41.       * @see Session#DUPS_OK_ACKNOWLEDGE 

  42.       */ 

  43. 

  44.     TopicSession

  45.     createTopicSession(boolean transacted,

  46.                        int acknowledgeMode) throws JMSException;

  47. 

  48. 

  49.     /** Creates a connection consumer for this connection (optional operation).

  50.       * This is an expert facility not used by regular JMS clients.

  51.       *  

  52.       * @param topic the topic to access

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

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

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

  56.       * for the message consumer.

  57.       * @param sessionPool the server session pool to associate with this 

  58.       * connection consumer

  59.       * @param maxMessages the maximum number of messages that can be

  60.       * assigned to a server session at one time

  61.       *

  62.       * @return the connection consumer

  63.       *

  64.       * @exception JMSException if the <CODE>TopicConnection</CODE> object fails

  65.       *                         to create a connection consumer due to some

  66.       *                         internal error or invalid arguments for 

  67.       *                         <CODE>sessionPool</CODE> and 

  68.       *                         <CODE>messageSelector</CODE>.

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

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

  71.       * @see javax.jms.ConnectionConsumer

  72.       */ 

  73. 

  74.     ConnectionConsumer

  75.     createConnectionConsumer(Topic topic,

  76.                              String messageSelector,

  77.                              ServerSessionPool sessionPool,

  78. 			     int maxMessages)

  79. 			     throws JMSException;

  80. 

  81. 

  82.     /** Create a durable connection consumer for this connection (optional operation). 

  83.       * This is an expert facility not used by regular JMS clients.

  84.       *                

  85.       * @param topic the topic to access

  86.       * @param subscriptionName durable subscription name

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

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

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

  90.       * for the message consumer.

  91.       * @param sessionPool the server session pool to associate with this 

  92.       * durable connection consumer

  93.       * @param maxMessages the maximum number of messages that can be

  94.       * assigned to a server session at one time

  95.       *

  96.       * @return the durable connection consumer

  97.       *  

  98.       * @exception JMSException if the <CODE>TopicConnection</CODE> object fails

  99.       *                         to create a connection consumer due to some

  100.       *                         internal error or invalid arguments for 

  101.       *                         <CODE>sessionPool</CODE> and 

  102.       *                         <CODE>messageSelector</CODE>.

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

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

  105.       * @see javax.jms.ConnectionConsumer

  106.       */

  107. 

  108.     ConnectionConsumer

  109.     createDurableConnectionConsumer(Topic topic,

  110. 				    String subscriptionName,

  111.                                     String messageSelector,

  112.                                     ServerSessionPool sessionPool,

  113. 				    int maxMessages)

  114.                              throws JMSException;

  115. }