# 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.

Copyright © Cloud Software Group, Inc. All rights reserved.