Chapter 11 Developing an EMS Client Application : Connection Factories

Connection Factories
A client must connect to a running instance of the EMS server to perform any JMS operations. A connection factory is an object that encapsulates the data used to define a client connection to an EMS server. The minimum factory parameters are the type of connection (e.g., ’generic’ for JMS 1.1 connections and ’topic’ or ’queue’ for JMS 1.0.2b connections) and the URL (host name, transport protocol and port id) for the client connection to the EMS server.
A connection factory is either dynamically created by the application or obtained from a data store by means of a naming service, such as a Java Naming and Directory Interface (JNDI) server or a Lightweight Directory Access Protocol (LDAP) server.
Looking up Connection Factories
EMS provides a JNDI implementation that can be used to store connection factories. Java, C, and C# clients can use the EMS JNDI implementation to lookup connection factories.
You can also store connection factories in any JNDI-compliant naming service or in an LDAP server. Java clients can lookup connection factories in any JNDI-compliant naming service. C and C# clients use LDAP servers.
Looking up Administered Objects Stored in EMS describes how to lookup a connection factory from an EMS server. Chapter 1, Using JNDI With Third-Party Naming/Directory Services in the TIBCO Enterprise Message Service Application Integration Guide describes how to look up connection factories from a third-party JNDI or LDAP server.
How to create connection factories in a EMS server is described in Creating and Modifying Administered Objects in EMS.
Dynamically Creating Connection Factories
Normally client applications use JNDI to look up a Connection Factory object. However, some situations require clients to connect to the server directly. To connect to the EMS server directly, the application must dynamically create a connection factory.
The following examples show how to create a connection factory in each supported language for JMS 1.1 connections. Each API also supports connection factories for JMS 1.1 XA connections.
In each example, the serverUrl parameter in these expressions is a string defining the protocol and the address of the running instance of the EMS Server. The serverUrl parameter has the form:
   serverUrl = protocol://host:port
The supported protocols are tcp and ssl. For example:
   serverUrl = tcp://server0:7222
For a fault-tolerant connection, you can specify two or more URLs. For example:
   serverUrl = tcp://server0:7222,tcp://server1:7344
See Configuring Clients for Fault-Tolerant Connections for more information. For details on using SSL for creating secure connections to the server, see Configuring SSL in EMS Clients and Creating Connection Factories for Secure Connections.
Java
To dynamically create a TibjmsConnectionFactory object in a Java client:
   ConnectionFactory factory = new
      com.tibco.tibjms.TibjmsConnectionFactory(serverUrl);
See the tibjmsMsgProducer.java sample client for a working example.
C
To dynamically create a tibemsConnectionFactory type in a C client:
   factory = tibemsConnectionFactory_Create();
   status = tibemsConnectionFactory_SetServerURL(
                factory, serverUrl);
See the tibemsMsgProducer.c sample client for a working example.
C#
To dynamically create a ConnectionFactory object in a C# client:
    ConnectionFactory factory = new
      TIBCO.EMS.ConnectionFactory(serverUrl);
See the csMsgProducer.cs sample client for a working example.
Setting Connection Attempts, Timeout and Delay Parameters
By default, a client will attempt to connect to the server two times with a 500 ms delay between each attempt. A client can modify this behavior by setting new connection attempt count and delay values. There are also a number of factors that may cause a client to hang while attempting to create a connection to the EMS server, so you can set a connection timeout value to abort a connection attempt after a specified period of time. For best results, timeouts should be at least 500 milliseconds. EMS also allows you to establish separate count, delay and timeout settings for reconnections after a fault-tolerant switchover, as described in Setting Reconnection Failure Parameters.
The following examples establish a connection count of 10, a delay of 1000 ms and a timeout of 1000 ms.
Java
Use the TibjmsConnectionFactory object’s setConnAttemptCount(), setConnAttemptDelay(), and setConnAttemptTimeout() methods to establish new connection failure parameters:
   factory.setConnAttemptCount(10);
   factory.setConnAttemptDelay(1000);
   factory.setConnAttemptTimeout(1000);
C
Use the tibemsConnectionFactory_SetConnectAttemptCount and tibemsConnectionFactory_SetConnectAttemptDelay functions to establish new connection failure parameters:
   status = tibemsConnectionFactory_SetConnectAttemptCount(
                factory, 10);
   status = tibemsConnectionFactory_SetConnectAttemptDelay(
                factory, 1000);
   status = tibemsConnectionFactory_SetConnectAttemptTimeout(
                factory, 1000);
C#
Use the ConnectionFactory.SetConnAttemptCount, ConnectionFactory.SetConnAttemptDelay, and ConnectionFactory.SetConnAttemptTimeout methods to establish new connection failure parameters:
   factory.setConnAttemptCount(10);
   factory.setConnAttemptDelay(1000);
   factory.setConnAttemptTimeout(1000);