public interface TopicConnection extends Connection
TopicConnection
object is an active connection to a
publish/subscribe JMS provider. A client uses a TopicConnection
object to create one or more TopicSession
objects
for producing and consuming messages.
A TopicConnection
can be used to create a
TopicSession
, from which
specialized topic-related objects can be created.
A more general, and recommended approach is to use the
Connection
object.
The TopicConnection
object
should be used to support existing code.
Connection
,
ConnectionFactory
,
TopicConnectionFactory
Modifier and Type | Method and Description |
---|---|
ConnectionConsumer |
createConnectionConsumer(Topic topic,
String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
Creates a connection consumer for this connection (optional operation).
|
ConnectionConsumer |
createDurableConnectionConsumer(Topic topic,
String subscriptionName,
String messageSelector,
ServerSessionPool sessionPool,
int maxMessages)
Create a durable connection consumer for this connection (optional operation).
|
TopicSession |
createTopicSession(boolean transacted,
int acknowledgeMode)
Creates a
TopicSession object,
specifying transacted and acknowledgeMode . |
close, createConnectionConsumer, createSession, createSession, createSession, createSharedConnectionConsumer, createSharedDurableConnectionConsumer, getClientID, getExceptionListener, getMetaData, setClientID, setExceptionListener, start, stop
TopicSession createTopicSession(boolean transacted, int acknowledgeMode) throws JMSException
TopicSession
object,
specifying transacted
and acknowledgeMode
.
The effect of setting the transacted
and acknowledgeMode
arguments depends on whether this method is called in a Java SE environment,
in the Java EE application client container, or in the Java EE web or EJB container.
If this method is called in the Java EE web or EJB container then the
effect of setting the transacted} and acknowledgeMode
arguments also depends on whether or not there is an active JTA transaction
in progress.
In a Java SE environment or in the Java EE application client container:
transacted
is set to true
then the session
will use a local transaction which may subsequently be committed or rolled back
by calling the session's commit
or rollback
methods.
The argument acknowledgeMode
is ignored.
transacted
is set to false
then the session
will be non-transacted. In this case the argument acknowledgeMode
is used to specify how messages received by this session will be acknowledged.
The permitted values are
Session.CLIENT_ACKNOWLEDGE
,
Session.AUTO_ACKNOWLEDGE
and
Session.DUPS_OK_ACKNOWLEDGE
.
For a definition of the meaning of these acknowledgement modes see the links below.
In a Java EE web or EJB container, when there is an active JTA transaction in progress:
transacted
and acknowledgeMode
are ignored.
The session will participate in the JTA transaction and will be committed or rolled back
when that transaction is committed or rolled back,
not by calling the session's commit
or rollback
methods.
Since both arguments are ignored, developers are recommended to use
createSession()
, which has no arguments, instead of this method.
In the Java EE web or EJB container, when there is no active JTA transaction in progress:
transacted
is set to false and acknowledgeMode
is set to
JMSContext.AUTO_ACKNOWLEDGE
or Session.DUPS_OK_ACKNOWLEDGE
then the
session will be non-transacted and messages will be acknowledged according
to the value of acknowledgeMode
.
transacted
is set to false and acknowledgeMode
is set to
JMSContext.CLIENT_ACKNOWLEDGE
then the JMS provider is recommended to
ignore the specified parameters and instead provide a non-transacted,
auto-acknowledged session. However the JMS provider may alternatively
provide a non-transacted session with client acknowledgement.
transacted
is set to true, then the JMS provider is recommended to
ignore the specified parameters and instead provide a non-transacted,
auto-acknowledged session. However the JMS provider may alternatively
provide a local transacted session.
transacted
to false and
acknowledgeMode
to JMSContext.AUTO_ACKNOWLEDGE
or
Session.DUPS_OK_ACKNOWLEDGE
since since applications which set
transacted
to false and set acknowledgeMode
to
JMSContext.CLIENT_ACKNOWLEDGE
, or which set transacted
to true, may not be portable.
Applications running in the Java EE web and EJB containers must not attempt
to create more than one active (not closed) Session
object per connection.
If this method is called in a Java EE web or EJB container when an active
Session
object already exists for this connection then a JMSException
may be thrown.
transacted
- indicates whether the session will use a local transaction,
except in the cases described above when this value is ignored.acknowledgeMode
- when transacted is false, indicates how messages received
by the session will be acknowledged, except in the cases described above
when this value is ignored.TopicSession
JMSException
- if the TopicConnection
object fails
to create a TopicSession
due to
Session.AUTO_ACKNOWLEDGE
,
Session.CLIENT_ACKNOWLEDGE
,
Session.DUPS_OK_ACKNOWLEDGE
ConnectionConsumer createConnectionConsumer(Topic topic, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
topic
- the topic to accessmessageSelector
- only messages with properties matching the
message selector expression are delivered. A value of null or
an empty string indicates that there is no message selector
for the message consumer.sessionPool
- the server session pool to associate with this
connection consumermaxMessages
- the maximum number of messages that can be
assigned to a server session at one timeJMSException
- if the TopicConnection
object fails
to create a connection consumer due to some
internal error or invalid arguments for
sessionPool
and
messageSelector
.InvalidDestinationException
- if an invalid topic is specified.InvalidSelectorException
- if the message selector is invalid.ConnectionConsumer
ConnectionConsumer createDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
createDurableConnectionConsumer
in interface Connection
topic
- the topic to accesssubscriptionName
- durable subscription namemessageSelector
- only messages with properties matching the
message selector expression are delivered. A value of null or
an empty string indicates that there is no message selector
for the message consumer.sessionPool
- the server session pool to associate with this
durable connection consumermaxMessages
- the maximum number of messages that can be
assigned to a server session at one timeJMSException
- if the TopicConnection
object fails
to create a connection consumer due to some
internal error or invalid arguments for
sessionPool
and
messageSelector
.InvalidDestinationException
- if an invalid topic is specified.InvalidSelectorException
- if the message selector is invalid.ConnectionConsumer
Copyright © 1996-2015, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.