001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.jms;
023:
024: /** A <CODE>TopicConnection</CODE> object is an active connection to a
025: * publish/subscribe JMS provider. A client uses a <CODE>TopicConnection</CODE>
026: * object to create one or more <CODE>TopicSession</CODE> objects
027: * for producing and consuming messages.
028: *
029: *<P>A <CODE>TopicConnection</CODE> can be used to create a
030: *<CODE>TopicSession</CODE>, from which
031: * specialized topic-related objects can be created.
032: * A more general, and recommended approach is to use the
033: * <CODE>Connection</CODE> object.
034: *
035: *
036: * <P>The <CODE>TopicConnection</CODE> object
037: * should be used to support existing code.
038: *
039: * @see javax.jms.Connection
040: * @see javax.jms.ConnectionFactory
041: * @see javax.jms.TopicConnectionFactory
042: */
043:
044: public interface TopicConnection extends Connection {
045:
046: /** Creates a <CODE>TopicSession</CODE> object.
047: *
048: * @param transacted indicates whether the session is transacted
049: * @param acknowledgeMode indicates whether the consumer or the
050: * client will acknowledge any messages it receives; ignored if the session
051: * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>,
052: * <code>Session.CLIENT_ACKNOWLEDGE</code>, and
053: * <code>Session.DUPS_OK_ACKNOWLEDGE</code>.
054: *
055: * @return a newly created topic session
056: *
057: * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
058: * to create a session due to some internal error or
059: * lack of support for the specific transaction
060: * and acknowledgement mode.
061: *
062: * @see Session#AUTO_ACKNOWLEDGE
063: * @see Session#CLIENT_ACKNOWLEDGE
064: * @see Session#DUPS_OK_ACKNOWLEDGE
065: */
066:
067: TopicSession createTopicSession(boolean transacted,
068: int acknowledgeMode) throws JMSException;
069:
070: /** Creates a connection consumer for this connection (optional operation).
071: * This is an expert facility not used by regular JMS clients.
072: *
073: * @param topic the topic to access
074: * @param messageSelector only messages with properties matching the
075: * message selector expression are delivered. A value of null or
076: * an empty string indicates that there is no message selector
077: * for the message consumer.
078: * @param sessionPool the server session pool to associate with this
079: * connection consumer
080: * @param maxMessages the maximum number of messages that can be
081: * assigned to a server session at one time
082: *
083: * @return the connection consumer
084: *
085: * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
086: * to create a connection consumer due to some
087: * internal error or invalid arguments for
088: * <CODE>sessionPool</CODE> and
089: * <CODE>messageSelector</CODE>.
090: * @exception InvalidDestinationException if an invalid topic is specified.
091: * @exception InvalidSelectorException if the message selector is invalid.
092: * @see javax.jms.ConnectionConsumer
093: */
094:
095: ConnectionConsumer createConnectionConsumer(Topic topic,
096: String messageSelector, ServerSessionPool sessionPool,
097: int maxMessages) throws JMSException;
098:
099: /** Create a durable connection consumer for this connection (optional operation).
100: * This is an expert facility not used by regular JMS clients.
101: *
102: * @param topic the topic to access
103: * @param subscriptionName durable subscription name
104: * @param messageSelector only messages with properties matching the
105: * message selector expression are delivered. A value of null or
106: * an empty string indicates that there is no message selector
107: * for the message consumer.
108: * @param sessionPool the server session pool to associate with this
109: * durable connection consumer
110: * @param maxMessages the maximum number of messages that can be
111: * assigned to a server session at one time
112: *
113: * @return the durable connection consumer
114: *
115: * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
116: * to create a connection consumer due to some
117: * internal error or invalid arguments for
118: * <CODE>sessionPool</CODE> and
119: * <CODE>messageSelector</CODE>.
120: * @exception InvalidDestinationException if an invalid topic is specified.
121: * @exception InvalidSelectorException if the message selector is invalid.
122: * @see javax.jms.ConnectionConsumer
123: */
124:
125: ConnectionConsumer createDurableConnectionConsumer(Topic topic,
126: String subscriptionName, String messageSelector,
127: ServerSessionPool sessionPool, int maxMessages)
128: throws JMSException;
129: }
|