progress.message.jclient
Interface Connection

All Superinterfaces:

Connection

All Known Subinterfaces:

Connection, QueueConnection, QueueConnection, TopicConnection, TopicConnection, XAConnection, XAQueueConnection, XATopicConnection

public interface Connection
extends Connection

Implementation of a JMS Connection A JMS Connection is a client's active connection to its JMS provider. It will typically allocate provider resources outside the Java virtual machine.

Connections support concurrent use.

A Connection serves several purposes:

• It encapsulates an open connection with a JMS provider. It typically represents an open TCP/IP socket between a client and a provider service daemon.
• Its creation is where client authenticating takes place.
• It can specify a unique client identifier.
• It provides ConnectionMetaData.
• It supports an optional ExceptionListener.

Due to the authentication and communication setup done when a Connection is created, a Connection is a relatively heavy-weight JMS object. Most clients will do all their messaging with a single Connection. Other more advanced applications may use several Connections. JMS does not architect a reason for using multiple connections; however, there may be operational reasons for doing so.

A JMS client typically creates a Connection; one or more Sessions; and a number of message producers and consumers. When a Connection is created it is in stopped mode. That means that no messages are being delivered.

It is typical to leave the Connection in stopped mode until setup is complete. At that point the Connection's start() method is called and messages begin arriving at the Connection's consumers. This setup convention minimizes any client confusion that may result from asynchronous message delivery while the client is still in the process of setting itself up.

A Connection can immediately be started and the setup can be done afterwards. Clients that do this must be prepared to handle asynchronous message delivery while they are still in the process of setting up.

A message producer can send messages while a Connection is stopped.

Version:

1.0 - December 1998

Author:

Bill Collins

See Also:

Connection

Method Summary

Session	createSession(boolean transacted, int acknowledgeMode, java.lang.String sessionName) Creates a Session object with an associated name.
java.lang.String[]	getBrokerReconnectURLs() Returns URLs available on the currently connected broker, that may be used for the purpose re-connection of fault-tolerant connections when temporary or permanent network failure is encountered.
java.lang.String	getBrokerURL() Get URL of broker actually connected to.
Channel	getChannel(java.lang.String channelID) Retrieve a reference to a channel with the given channelID.
java.lang.String	getConnectID() Get the connect ID for this connection.
int	getConnectionState() Get connection state, one of ACTIVE, RECONNECTING, FAILED or CLOSED.
ConnectionStateChangeListener	getConnectionStateChangeListener() Get connection state change listener.
java.lang.String	getRoutingNodeName() Returns the name of the DRA routing node currently associated with the connection.
java.lang.String[]	getStandbyBrokerReconnectURLs() Returns URLs available on a standby broker, if any, which is paired for fault-tolerance with the currently connected broker, and that may be used for the purpose re-connection to a standby broker in the event of currently connected broker failure.
java.util.Enumeration	getUnfinishedChannelIDs() Return an enumeration of channel identifiers.
java.util.Enumeration	getUnfinishedChannels() Return an enumeration of channels.
java.lang.String	getUsername() Get the user of this connection.
boolean	hasUnfinishedChannel(java.lang.String channelID) Check if this connection has a channel with the given channelID.
boolean	hasUnfinishedChannels() Check if this connection has any unfinished channels.
boolean	isFaultTolerant() Returns true if the connection is fault tolerant For a connection to be fault-tolerant, fault-tolerant must be set in the ConnectionFactory, and the broker must support(be licensed for) fault-tolerance.
boolean	isSecure()
void	setConnectionStateChangeListener(ConnectionStateChangeListener listener) Set connection state change listener.
void	setPingInterval(long interval) Enable/disable sending active pings on this connection.
void	setRejectionListener(RejectionListener rl) Sets a listener to receive errors on messages rejected by the Broker when persistence is enabled and messages are sent asynchronously from the persistent store.

Methods inherited from interface javax.jms.Connection

close, createConnectionConsumer, createDurableConnectionConsumer, createSession, getClientID, getExceptionListener, getMetaData, setClientID, setExceptionListener, start, stop

Method Detail

getBrokerURL

java.lang.String getBrokerURL()

Get URL of broker actually connected to.

Returns:

URL of broker actually connected to. If called after the connection is closed, the last connected URL is returned.

getStandbyBrokerReconnectURLs

java.lang.String[] getStandbyBrokerReconnectURLs()

Returns URLs available on a standby broker, if any, which is paired for fault-tolerance with the currently connected broker, and that may be used for the purpose re-connection to a standby broker in the event of currently connected broker failure.

Re-connection is automatically performed by the client runtime. Standby broker reconnect URLs are provided for informational use.

The standby broker reconnect URLs are derived from the broker configuration. If a default routing URL is configured on the standby, this will be used for standby re-connection. Otherwise, standby broker acceptors URLs, configured with the same acceptor name as the currently connected broker URL are used for re-connection.

If called after the connection is closed, the last known standby reconnect URLs are returned.

If the currently connected broker is standalone, or, if from the configuration, no redundant URLs are present on the standby, or, if the connection is non fault-tolerant, null is returned.

Returns:

an array of URLs to the standby broker.

See Also:

getBrokerURL(), getBrokerReconnectURLs(), isFaultTolerant()

getBrokerReconnectURLs

java.lang.String[] getBrokerReconnectURLs()

Returns URLs available on the currently connected broker, that may be used for the purpose re-connection of fault-tolerant connections when temporary or permanent network failure is encountered.

Re-connection is automatically performed by the client runtime. Broker reconnect URLs are provided for informational use.

The broker reconnect URLs are derived from the broker configuration. If a default routing URL is configured on the broker, the currently connected URL is used for reconnection. Otherwise, acceptors URLs, configured with the same acceptor name as the currently connectedURL are used for reconnection.

If called after the connection is closed, the last known reconnect URLs are returned.

If the connection is non fault-tolerant, returns null.

Returns:

an array of reconnect URLs

See Also:

getBrokerURL(), getStandbyBrokerReconnectURLs(), isFaultTolerant()

getRoutingNodeName

java.lang.String getRoutingNodeName()

Returns the name of the DRA routing node currently associated with the connection.

Returns:

a routing node name

getConnectionState

int getConnectionState()

Get connection state, one of ACTIVE, RECONNECTING, FAILED or CLOSED.

A non fault-tolerant connection will never see a RECONNECTING value. This method may be called after the connection is closed.

Returns:

connection state

See Also:

Constants.ACTIVE, Constants.RECONNECTING, Constants.FAILED, Constants.CLOSED, ConnectionStateChangeListener, setConnectionStateChangeListener(ConnectionStateChangeListener), getConnectionStateChangeListener()

setConnectionStateChangeListener

void setConnectionStateChangeListener(ConnectionStateChangeListener listener)

Set connection state change listener.

See Also:

ConnectionStateChangeListener, getConnectionStateChangeListener()

isFaultTolerant

boolean isFaultTolerant()

Returns true if the connection is fault tolerant

For a connection to be fault-tolerant, fault-tolerant must be set in the ConnectionFactory, and the broker must support(be licensed for) fault-tolerance.

See Also:

ConnectionFactory.setFaultTolerant(java.lang.Boolean)

isSecure

boolean isSecure()

Returns:

true, if the connection is made to a secured broker.

getConnectionStateChangeListener

ConnectionStateChangeListener getConnectionStateChangeListener()

Get connection state change listener.

See Also:

ConnectionStateChangeListener, setConnectionStateChangeListener(ConnectionStateChangeListener)

getConnectID

java.lang.String getConnectID()

Get the connect ID for this connection. This is a non-JMS public method.

Returns:

the connect ID of connection.

getUsername

java.lang.String getUsername()

Get the user of this connection.

Returns:

the user of connection.

setPingInterval

void setPingInterval(long interval)

Enable/disable sending active pings on this connection. This is a non-JMS public method.

Parameters:

interval - indicates the interval in seconds for sending a ping. Setting interval to 0 or any negative value effectively disables the ping.

setRejectionListener

void setRejectionListener(RejectionListener rl)
                          throws JMSException

Sets a listener to receive errors on messages rejected by the Broker when persistence is enabled and messages are sent asynchronously from the persistent store. This is a non-JMS public method.

Parameters:

rl - an object that implements the RejectionListener interface

Throws:

JMSException

hasUnfinishedChannel

boolean hasUnfinishedChannel(java.lang.String channelID)
                             throws JMSException

Check if this connection has a channel with the given channelID. This feature is specific to PTP domains.

Parameters:

channelID - The channelID of the channel in question.

Returns:

True If this channel has an active channelID with this given channelID.

Throws:

JMSException - If there is an internal JMS Error.

hasUnfinishedChannels

boolean hasUnfinishedChannels()
                              throws JMSException

Check if this connection has any unfinished channels. This feature is specific to PTP domains.

Returns:

True If this connection has any unfinished channels.

Throws:

JMSException - If there is an internal JMS Error.

getChannel

Channel getChannel(java.lang.String channelID)
                   throws JMSException,
                          java.io.IOException

Retrieve a reference to a channel with the given channelID. This feature is specific to PTP domains.

Parameters:

channelID - The channelID of the channel in question.

Throws:

JMSException - If there is an internal JMS Error.

java.io.IOException - If there is an IOException while the channel is being recovered.

getUnfinishedChannels

java.util.Enumeration getUnfinishedChannels()
                                            throws JMSException,
                                                   java.io.IOException

Return an enumeration of channels. This feature is specific to PTP domains.

This method returns an enumeration of Channel objects.

Returns:

an enumeration of channels.

Throws:

JMSException - If there is an internal JMS Error

java.io.IOException - If there is an issue accessing channel recovery information

getUnfinishedChannelIDs

java.util.Enumeration getUnfinishedChannelIDs()
                                              throws JMSException,
                                                     java.io.IOException

Return an enumeration of channel identifiers. This method returns an enumeration of String objects that represents the IDs of the channels that are unfinished on this client. This feature is specific to PTP domains.

Returns:

an enumeration of ChannelID strings.

Throws:

JMSException - If there is an internal JMS Error.

java.io.IOException - If there is an issue accessing channel recovery information.

createSession

Session createSession(boolean transacted,
                      int acknowledgeMode,
                      java.lang.String sessionName)
                      throws JMSException

Creates a Session object with an associated name.

Parameters:

transacted - indicates whether the session is transacted

acknowledgeMode - indicates whether the consumer or the client will acknowledge any messages it receives; ignored if the session is transacted. Legal values are Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, and Session.DUPS_OK_ACKNOWLEDGE.

sessionName - provides a name for the session; this is an informational label to help administrators identify the session, particularly in the Sonic management tools

Returns:

a newly created session

Throws:

JMSException - if the Connection object fails to create a session due to some internal error or lack of support for the specific transaction and acknowledgement mode.

See Also:

Session.AUTO_ACKNOWLEDGE, Session.CLIENT_ACKNOWLEDGE, Session.DUPS_OK_ACKNOWLEDGE, Session.getSessionName()