factories.conf

This file defines the connection factories for the internal JNDI names.

The file consists of factory definitions with this format: 

[factory-name] # mandatory -- square brackets included
  type = generic|xageneric|topic|queue|xatopic|xaqueue|
  url = url-string
  metric = connections | byte_rate
  clientID = client-id
  [connect_attempt_count|connect_attempt_delay|
  connect_attempt_timeout|reconnect_attempt_count|
  reconnect_attempt_delay|reconnect_attempt_timeout = value]
  [ssl-prop = value]*
Parameter Name Description
Mandatory Parameters

These parameters are required. Values given to these parameters cannot be overridden using API calls.

[factory-name] [factory-name] is the name of the connection factory.

Note that the square brackets [ ] DO NOT indicate that the factory-name is optional; they must be included around the name.

type Type of the connection factory. The value can be:
  • generic: Generic connection
  • xageneric: Generic XA connection
  • topic: Topic connection
  • queue: Queue connection
  • xatopic: XA topic connection
  • xaqueue: XA queue connection
url This string specifies the servers to which this factory creates connections:
  • A single URL specifies a unique server. For example: 
    tcp://host1:8222
  • A pair of URLs separated by a comma specifies a pair of fault-tolerant servers. For example: 
    tcp://host1:8222,tcp://backup1:8222
  • A set of URLs separated by vertical bars specifies a load balancing among those servers. For example: 
    tcp://a:8222|tcp://b:8222|tcp://c:8222
  • You can combine load balancing with fault tolerance. For example: 
    tcp://a1:8222,tcp://a2:8222|tcp://b1:8222,tcp://b2:8222

    This example defines two servers (a and b), each of which has a fault-tolerant backup. The client program checks the load on the active a server and the active b server, and connects to the one that has the smaller load. If it cannot connect to one of the active servers, the client attempts to connect to the standby server. For example, if it cannot connect to b1, it connects to b2.

The connection URL cannot exceed 1000 characters.

For cautionary information, see Load Balancing.

Optional Parameters

These parameters are optional. The values of these parameters can be overridden using API calls.

metric The factory uses this metric to balance the load among a group of servers:
  • connections—Connect to the server with the fewest client connections.
  • byte_rate—Connect to the server with the lowest byte rate. Byte rate is a statistic that includes both inbound and outbound data.

When this parameter is absent, the default metric is connections.

For cautionary information, see Load Balancing.

clientID The factory associates this client ID string with the connections that it creates. The client ID cannot exceed 255 characters in length.
connect_attempt_count A client program attempts to connect to its server (or in fault-tolerant configurations, it iterates through its URL list) until it establishes its first connection to an EMS server. This property determines the maximum number of iterations. When absent, the default is 2.
connect_attempt_delay When attempting a first connection, the client sleeps for this interval (in milliseconds) between attempts to connect to its server (or in fault-tolerant configurations, iterations through its URL list). When absent, the default is 500 milliseconds.
connect_attempt_timeout When attempting to connect to the EMS server, you can set this connection timeout period to abort the connection attempt after a specified period of time (in milliseconds).
reconnect_attempt_count After losing its server connection, a client program configured with more than one server URL attempts to reconnect, iterating through its URL list until it re-establishes a connection with an EMS server. This property determines the maximum number of iterations. When absent, the default is 4.
reconnect_attempt_delay When attempting to reconnect, the client sleeps for this interval (in milliseconds) between iterations through its URL list. When absent, the default is 500 milliseconds.
reconnect_attempt_timeout When attempting to reconnect to the EMS server, you can set this connection timeout period to abort the connection attempt after a specified period of time (in milliseconds).
ssl-prop SSL properties for connections that this factory creates.

For further information on SSL, refer to SSL Protocol.

Example

[north_america]
  type = topic
  url = tcp://localhost:7222,tcp://server2:7222
  clientID = "Sample Client ID"
  ssl_verify_host = disabled

Configuration

To configure connection factories in this file, we recommend using the tibemsadmin tool; see create factory.

Load Balancing

Warning: Do not specify load balancing in situations with durable subscribers.

If a client program that a creates durable subscriber connects to server A using a load-balanced connection factory, then server A creates and supports the durable subscription. If the client program exits and restarts, and this time connects to server B, then server B creates and supports a new durable subscription—however, pending messages on server A remain there until the client reconnects to server A.

Do not specify load balancing when your application requires strict message ordering.

Load balancing chooses from among multiple servers, which inherently violates strict ordering.