-
- All Superinterfaces:
AutoCloseable
,Connection
- All Known Subinterfaces:
XATopicConnection
public interface TopicConnection extends Connection
ATopicConnection
object is an active connection to a publish/subscribe Jakarta Messaging provider. A client uses aTopicConnection
object to create one or moreTopicSession
objects for producing and consuming messages.A
TopicConnection
can be used to create aTopicSession
, from which specialized topic-related objects can be created. A more general, and recommended approach is to use theConnection
object.The
TopicConnection
object should be used to support existing code.- Since:
- JMS 1.0
- Version:
- Jakarta Messaging 2.0
- See Also:
Connection
,ConnectionFactory
,TopicConnectionFactory
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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 aTopicSession
object, specifyingtransacted
andacknowledgeMode
.-
Methods inherited from interface jakarta.jms.Connection
close, createConnectionConsumer, createSession, createSession, createSession, createSharedConnectionConsumer, createSharedDurableConnectionConsumer, getClientID, getExceptionListener, getMetaData, setClientID, setExceptionListener, start, stop
-
-
-
-
Method Detail
-
createTopicSession
TopicSession createTopicSession(boolean transacted, int acknowledgeMode) throws JMSException
Creates aTopicSession
object, specifyingtransacted
andacknowledgeMode
.The effect of setting the
transacted
andacknowledgeMode
arguments depends on whether this method is called in a Java SE environment, in the Jakarta EE application client container, or in the Jakarta EE web or EJB container. If this method is called in the Jakarta EE web or EJB container then the effect of setting the transacted} andacknowledgeMode
arguments also depends on whether or not there is an active JTA transaction in progress.In a Java SE environment or in the Jakarta EE application client container:
- If
transacted
is set totrue
then the session will use a local transaction which may subsequently be committed or rolled back by calling the session'scommit
orrollback
methods. The argumentacknowledgeMode
is ignored. - If
transacted
is set tofalse
then the session will be non-transacted. In this case the argumentacknowledgeMode
is used to specify how messages received by this session will be acknowledged. The permitted values areSession.CLIENT_ACKNOWLEDGE
,Session.AUTO_ACKNOWLEDGE
andSession.DUPS_OK_ACKNOWLEDGE
. For a definition of the meaning of these acknowledgement modes see the links below.
In a Jakarta EE web or EJB container, when there is an active JTA transaction in progress:
- Both arguments
transacted
andacknowledgeMode
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'scommit
orrollback
methods. Since both arguments are ignored, developers are recommended to usecreateSession()
, which has no arguments, instead of this method.
In the Jakarta EE web or EJB container, when there is no active JTA transaction in progress:
- If
transacted
is set to false andacknowledgeMode
is set toJMSContext.AUTO_ACKNOWLEDGE
orSession.DUPS_OK_ACKNOWLEDGE
then the session will be non-transacted and messages will be acknowledged according to the value ofacknowledgeMode
. - If
transacted
is set to false andacknowledgeMode
is set toJMSContext.CLIENT_ACKNOWLEDGE
then the Jakarta Messaging provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the Jakarta Messaging provider may alternatively provide a non-transacted session with client acknowledgement. - If
transacted
is set to true, then the Jakarta Messaging provider is recommended to ignore the specified parameters and instead provide a non-transacted, auto-acknowledged session. However the Jakarta Messaging provider may alternatively provide a local transacted session. - Applications are recommended to set
transacted
to false andacknowledgeMode
toJMSContext.AUTO_ACKNOWLEDGE
orSession.DUPS_OK_ACKNOWLEDGE
since since applications which settransacted
to false and setacknowledgeMode
toJMSContext.CLIENT_ACKNOWLEDGE
, or which settransacted
to true, may not be portable.
Applications running in the Jakarta 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 Jakarta EE web or EJB container when an activeSession
object already exists for this connection then aJMSException
may be thrown.- Parameters:
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.- Returns:
- a newly created
TopicSession
- Throws:
JMSException
- if theTopicConnection
object fails to create aTopicSession
due to- some internal error,
- lack of support for the specific transaction and acknowledgement mode, or
- because this method is being called in a Jakarta EE web or EJB application and an active session already exists for this connection.
- Since:
- JMS 1.1
- See Also:
Session.AUTO_ACKNOWLEDGE
,Session.CLIENT_ACKNOWLEDGE
,Session.DUPS_OK_ACKNOWLEDGE
- If
-
createConnectionConsumer
ConnectionConsumer createConnectionConsumer(Topic topic, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
Creates a connection consumer for this connection (optional operation). This is an expert facility not used by regular Jakarta Messaging clients.- Parameters:
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 time- Returns:
- the connection consumer
- Throws:
JMSException
- if theTopicConnection
object fails to create a connection consumer due to some internal error or invalid arguments forsessionPool
andmessageSelector
.InvalidDestinationException
- if an invalid topic is specified.InvalidSelectorException
- if the message selector is invalid.- See Also:
ConnectionConsumer
-
createDurableConnectionConsumer
ConnectionConsumer createDurableConnectionConsumer(Topic topic, String subscriptionName, String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws JMSException
Create a durable connection consumer for this connection (optional operation). This is an expert facility not used by regular Jakarta Messaging clients.- Specified by:
createDurableConnectionConsumer
in interfaceConnection
- Parameters:
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 time- Returns:
- the durable connection consumer
- Throws:
JMSException
- if theTopicConnection
object fails to create a connection consumer due to some internal error or invalid arguments forsessionPool
andmessageSelector
.InvalidDestinationException
- if an invalid topic is specified.InvalidSelectorException
- if the message selector is invalid.- See Also:
ConnectionConsumer
-
-