ConnectionFactories and Connection objects

A ConnectionFactory object provides a template that an application uses to create a Connection object. The application uses the Connection object to create a Session object.

For .NET, XMS application first uses an XMSFactoryFactory object to get a reference to a ConnectionFactory object that is appropriate to the required type of protocol. This ConnectionFactory object can then produce connections only for that protocol type.

An XMS application can create multiple connections, and a multithreaded application can use a single Connection object concurrently on multiple threads. A Connection object encapsulates a communications connection between an application and a messaging server.

A connection serves several purposes:

• When an application creates a connection, the application can be authenticated.
• An application can associate a unique client identifier with a connection. The client identifier is used to support durable subscriptions in the publish/subscribe domain. The client identifier can be set in two ways:

  The preferred way of assigning a connections client identifier, is to configure in a client-specific ConnectionFactory object using properties and transparently assign it to the connection it creates.

  An alternative way of assigning a client identifier is to use a provider-specific value that is set on the Connection object. This value does not override the identifier that has been administratively configured. It is provided for the case where no administratively specified identifier exists. If an administratively specified identifier does exist, an attempt to override it with a provider-specific value causes an exception to be thrown. If an application explicitly sets an identifier, it must do it immediately after creating the connection and before any other action on the connection is taken; otherwise, an exception is thrown.

An XMS application typically creates a connection, one or more sessions, and a number of message producers and message consumers.

Create a connection is relatively expensive in terms of system resources because it involves establishing a communications connection, and it might also involve authenticating the application.

Connection started and stopped mode

A connection can operate in either started or stopped mode.

When an application creates a connection, the connection is in stopped mode. When the connection is in stopped mode, the application can initialize sessions, and it can send messages but cannot receive them, either synchronously or asynchronously.

An application can start a connection by calling the Start Connection method. When the connection is in started mode, the application can send and receive messages. The application can then stop and restart the connection by calling the Stop Connection and Start Connection methods.

Connection closure

An application closes a connection by calling the Close Connection method. When an application closes a connection, XMS performs the following actions:

• It closes all the sessions associated with the connection and deletes certain objects associated with these sessions. For more information about which objects are deleted, see Object deletion. At the same time, XMS rolls back any transactions currently in progress within the sessions.
• It ends the communications connection with the messaging server.
• It releases the memory and other internal resources used by the connection.

XMS does not acknowledge the receipt of any messages that it has failed to acknowledge during a session, prior to closing the connection. For more information about acknowledging the receipt of messages, see Message acknowledgment.

Exception handling

XMS .NET exceptions are all derived from System.Exception. For more information, see Error handling in .NET.

Connection to a service integration bus

An XMS application can connect to a WebSphere Application Server service integration bus either by using a direct TCP/IP connection or by using HTTP over TCP/IP.

The HTTP protocol can be used in situations where a direct TCP/IP connection is not possible. One common situation is when communicating through a firewall, such as when two enterprises exchange messages. Using HTTP to communicate through a firewall is often referred to as HTTP tunneling. HTTP tunneling, however, is inherently slower than using a direct TCP/IP connection because HTTP headers add significantly to the amount of data that is transferred, and because the HTTP protocol requires more communication flows than TCP/IP.

To create a TCP/IP connection, an application can use a connection factory whose XMSC_WPM_TARGET_TRANSPORT_CHAIN property is set to XMSC_WPM_TARGET_TRANSPORT_CHAIN_BASIC. This is the default value of the property. If the connection is created successfully, the XMSC_WPM_CONNECTION_PROTOCOL property of the connection is set to XMSC_WPM_CP_TCP.

To create a connection that uses HTTP, an application must use a connection factory whose XMSC_WPM_TARGET_TRANSPORT_CHAIN property is set to the name of an inbound transport chain, that is configured to use an HTTP transport channel. If the connection is created successfully, the XMSC_WPM_CONNECTION_PROTOCOL property of the connection is set to XMSC_WPM_CP_HTTP. For information about how to configure transport chains, see Configure transport chains in the WebSphere Application Server product documentation.

An application has a similar choice of communication protocols when connecting to a bootstrap server. The XMSC_WPM_PROVIDER_ENDPOINTS property of a connection factory is a sequence of one or more endpoint addresses of bootstrap servers. The bootstrap transport chain component of each endpoint address can be either XMSC_WPM_BOOTSTRAP_TCP, for a TCP/IP connection to a bootstrap server or XMSC_WPM_BOOTSTRAP_HTTP, for a connection that uses HTTP.