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. /** For application servers, <CODE>Connection</CODE> objects provide a special 

  9.   * facility 

  10.   * for creating a <CODE>ConnectionConsumer</CODE> (optional). The messages it 

  11.   * is to consume are 

  12.   * specified by a <CODE>Destination</CODE> and a message selector. In addition,

  13.   * a <CODE>ConnectionConsumer</CODE> must be given a 

  14.   * <CODE>ServerSessionPool</CODE> to use for 

  15.   * processing its messages.

  16.   *

  17.   * <P>Normally, when traffic is light, a <CODE>ConnectionConsumer</CODE> gets a

  18.   * <CODE>ServerSession</CODE> from its pool, loads it with a single message, and

  19.   * starts it. As traffic picks up, messages can back up. If this happens, 

  20.   * a <CODE>ConnectionConsumer</CODE> can load each <CODE>ServerSession</CODE>

  21.   * with more than one 

  22.   * message. This reduces the thread context switches and minimizes resource 

  23.   * use at the expense of some serialization of message processing.

  24.   *

  25.   * @version     1.0 - 3 August 1998

  26.   * @author      Mark Hapner

  27.   * @author      Rich Burridge

  28.   *

  29.   * @see javax.jms.QueueConnection#createConnectionConsumer

  30.   * @see javax.jms.TopicConnection#createConnectionConsumer

  31.   * @see javax.jms.TopicConnection#createDurableConnectionConsumer

  32.   */

  33. 

  34. public interface ConnectionConsumer {

  35. 

  36.     /** Gets the server session pool associated with this connection consumer.

  37.       *  

  38.       * @return the server session pool used by this connection consumer

  39.       *  

  40.       * @exception JMSException if the JMS provider fails to get the server 

  41.       *                         session pool associated with this consumer due

  42.       *                         to some internal error.

  43.       */

  44. 

  45.     ServerSessionPool 

  46.     getServerSessionPool() throws JMSException; 

  47. 

  48.  

  49.     /** Closes the connection consumer.

  50.       *

  51.       * <P>Since a provider may allocate some resources on behalf of a 

  52.       * connection consumer outside the Java virtual machine, clients should 

  53.       * close these resources when

  54.       * they are not needed. Relying on garbage collection to eventually 

  55.       * reclaim these resources may not be timely enough.

  56.       *  

  57.       * @exception JMSException if the JMS provider fails to release resources 

  58.       *                         on behalf of the connection consumer or fails

  59.       *                         to close the connection consumer.

  60.       */

  61. 

  62.     void 

  63.     close() throws JMSException; 

  64. }