001: /*
002: * @(#)TopicConnection.java 1.19 02/04/09
003: *
004: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * SUN PROPRIETARY/CONFIDENTIAL.
007: * This software is the proprietary information of Sun Microsystems, Inc.
008: * Use is subject to license terms.
009: *
010: */
011:
012: package javax.jms;
013:
014: /** A <CODE>TopicConnection</CODE> object is an active connection to a
015: * publish/subscribe JMS provider. A client uses a <CODE>TopicConnection</CODE>
016: * object to create one or more <CODE>TopicSession</CODE> objects
017: * for producing and consuming messages.
018: *
019: *<P>A <CODE>TopicConnection</CODE> can be used to create a
020: *<CODE>TopicSession</CODE>, from which
021: * specialized topic-related objects can be created.
022: * A more general, and recommended approach is to use the
023: * <CODE>Connection</CODE> object.
024: *
025: *
026: * <P>The <CODE>TopicConnection</CODE> object
027: * should be used to support existing code.
028: *
029: * @version 1.1 - February 2, 2002
030: * @author Mark Hapner
031: * @author Rich Burridge
032: * @author Kate Stout
033: *
034: * @see javax.jms.Connection
035: * @see javax.jms.ConnectionFactory
036: * @see javax.jms.TopicConnectionFactory
037: */
038:
039: public interface TopicConnection extends Connection {
040:
041: /** Creates a <CODE>TopicSession</CODE> object.
042: *
043: * @param transacted indicates whether the session is transacted
044: * @param acknowledgeMode indicates whether the consumer or the
045: * client will acknowledge any messages it receives; ignored if the session
046: * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>,
047: * <code>Session.CLIENT_ACKNOWLEDGE</code>, and
048: * <code>Session.DUPS_OK_ACKNOWLEDGE</code>.
049: *
050: * @return a newly created topic session
051: *
052: * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
053: * to create a session due to some internal error or
054: * lack of support for the specific transaction
055: * and acknowledgement mode.
056: *
057: * @see Session#AUTO_ACKNOWLEDGE
058: * @see Session#CLIENT_ACKNOWLEDGE
059: * @see Session#DUPS_OK_ACKNOWLEDGE
060: */
061:
062: TopicSession createTopicSession(boolean transacted,
063: int acknowledgeMode) throws JMSException;
064:
065: /** Creates a connection consumer for this connection (optional operation).
066: * This is an expert facility not used by regular JMS clients.
067: *
068: * @param topic the topic to access
069: * @param messageSelector only messages with properties matching the
070: * message selector expression are delivered. A value of null or
071: * an empty string indicates that there is no message selector
072: * for the message consumer.
073: * @param sessionPool the server session pool to associate with this
074: * connection consumer
075: * @param maxMessages the maximum number of messages that can be
076: * assigned to a server session at one time
077: *
078: * @return the connection consumer
079: *
080: * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
081: * to create a connection consumer due to some
082: * internal error or invalid arguments for
083: * <CODE>sessionPool</CODE> and
084: * <CODE>messageSelector</CODE>.
085: * @exception InvalidDestinationException if an invalid topic is specified.
086: * @exception InvalidSelectorException if the message selector is invalid.
087: * @see javax.jms.ConnectionConsumer
088: */
089:
090: ConnectionConsumer createConnectionConsumer(Topic topic,
091: String messageSelector, ServerSessionPool sessionPool,
092: int maxMessages) throws JMSException;
093:
094: /** Create a durable connection consumer for this connection (optional operation).
095: * This is an expert facility not used by regular JMS clients.
096: *
097: * @param topic the topic to access
098: * @param subscriptionName durable subscription name
099: * @param messageSelector only messages with properties matching the
100: * message selector expression are delivered. A value of null or
101: * an empty string indicates that there is no message selector
102: * for the message consumer.
103: * @param sessionPool the server session pool to associate with this
104: * durable connection consumer
105: * @param maxMessages the maximum number of messages that can be
106: * assigned to a server session at one time
107: *
108: * @return the durable connection consumer
109: *
110: * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
111: * to create a connection consumer due to some
112: * internal error or invalid arguments for
113: * <CODE>sessionPool</CODE> and
114: * <CODE>messageSelector</CODE>.
115: * @exception InvalidDestinationException if an invalid topic is specified.
116: * @exception InvalidSelectorException if the message selector is invalid.
117: * @see javax.jms.ConnectionConsumer
118: */
119:
120: ConnectionConsumer createDurableConnectionConsumer(Topic topic,
121: String subscriptionName, String messageSelector,
122: ServerSessionPool sessionPool, int maxMessages)
123: throws JMSException;
124: }
|