The purpose of connection factories is to hide physical connection properties from JMS clients. Instead, an object (a connection factory) is registered in JNDI from which physical connections are created.
Connection factories are created as a sub-entity of a JMS listener, so each connection factory is bound to a specific JMS listener and inherits the physical connection properties like port number and socket factory. Once a connection factory is created, it is registered automatically in JNDI under the specific name. There is always one default connection factory per JMS listener which is also registered in JNDI. The name of those connection factories consists of <listener>@<router>, e.g. for a listener "plainsocket" on "router1", the connection factory is named "plainsocket@router1".
The following configuration of the JMS Swiftlet shows the definition of 1 listener and with some connection factories:
<swiftlet name="sys$jms">
<intravm-connection-factories/>
<listeners>
<listener name="plainsocket" port="4001">
<connection-factories>
<connection-factory name="QueueConnectionFactory"/>
<connection-factory name="TopicConnectionFactory"/>
<connection-factory name="plainsocket@router1"/>
<connection-factory name="plainsocket_appserver@router1"
thread-context-classloader-for-getobject="true"/>
<connection-factory name="plainsocket_recover@router1"
smqp-consumer-cache-size="10"/>
</connection-factories>
<host-access-list/>
</listener>
</listeners>
</swiftlet>
A connection factory contains various attribute definitions which define the behavior of the JMS clients, connecting via the connection factory:
| Attribute | Default | Meaning |
|---|---|---|
| jms-client-id | null | Presets the JMS client id. If none is specified (default), a random client id is created. Note that it is not possible to create a durable subscriber without a client id or with a random one. The router will reject it. |
| jms-default-delivery-mode | persistent | Presets the JMS default delivery mode for message producers. The default value is compliant with the JMS specification. |
| jms-default-message-ttl | 0 | Presets the JMS default message time-to-live for message producers. The default value is compliant with the JMS specification. |
| jms-default-message-priority | 4 | Presets the JMS default message priority for message producers. The default value is compliant with the JMS specification. |
| jms-default-message-id-enabled | true | Presets whether a message id should be generated for produced messages. The default value is compliant with the JMS specification. |
| jms-default-message-timestamp-enabled | true | Presets whether a time stamp should be generated for produced messages. The default value is compliant with the JMS specification. |
| thread-context-classloader-for-getobject | false | Presets whether the thread contex class loader should be used during the deserialization of objects returned from an ObjectMessage' getObject() method. This is important if SwiftMQ is integrated into app servers which use different class loaders for message-driven beans. |
| smqp-producer-reply-interval | 20 | Contains the interval after which a message producer waits on a reply and thus can act on flow control delays. This attributes takes only effect for non-persistent messages. The default value is optimal in conjunction with a smqp-consumer-cache-size of 500. |
| smqp-consumer-cache-size | 500 | Contains the size of the client message cache of message consumers. The router sends up to this size without waiting for a reply. This attribute effects performance and the default value is optimal in conjunction with a smqp-producer-reply-interval of 20. |
| smqp-consumer-cache-size-kb | 2048 | Limits the size of the cache per consumer to the specified value in KB. A value of -1 disables it. Limiting the size is useful to avoid out of memory errors if large messages are transfered. Since 7.5.0. |
| reconnect-enabled | depends | Enables transparent reconnect for JMS clients. Default "true" for SwiftMQ HA Router, "false" for non-HA Router. Since 6.0.0. |
| reconnect-max-retries | 50 | Specifies the max. retries for reconnect attemts. Since 6.0.0. |
| reconnect-delay | 10000 | Specifies the delay in ms between reconnect retries. Since 6.0.0. |
| duplicate-message-detection | depends | Enables/disables duplicate message detection at the client side. Must be enabled if reconnect is enabled. Default "true" for SwiftMQ HA Router, "false" for non-HA Router. Since 6.0.0. |
| duplicate-backlog-size | 30000 | Specifies the max. size of the duplicate backlog per connection (JMS Message Ids) at the client side. Since 6.0.0. |
| client-input-extend-size | 65536 | Specifies the extend size in bytes to increase the JMS client's network input buffer once it is full. |
| client-output-buffer-size | 131072 | Specifies the initial size in bytes of the JMS client's network output buffer. |
| client-output-extend-size | 65536 | Specifies the extend size in bytes to increase the JMS client's network output buffer once it is full. |
Usually the code of a remote JMS client contains this part:
include java.util.*;
include javax.naming.*;
include javax.jms.*;
...
// Create the Hashtable with the JNDI environment properties
Hashtable env = new Hashtable();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.swiftmq.jndi.InitialContextFactoryImpl");
// Use a JMS listener on localhost:4001 for the JNDI connection
env.put(Context.PROVIDER_URL, "smqp://localhost:4001/timeout=10000");
InitialContext ctx = new InitialContext(env);
// Lookup a connection factory and a topic
TopicConnectionFactory tcf = (TopicConnectionFactory) ctx.lookup("TopicConnectionFactory");
Topic topic = (Topic) ctx.lookup("testtopic");
ctx.close();
// Create a topic connection
TopicConnection connection = tcf.createTopicConnection();
...
Usually, JMS connection factory are obtained from SwiftMQ's JNDI. However, it is also possible to create JMS connection factories by yourself without performing a JNDI lookup. It is not recommended, because of the proprietary code in the client program, but it is sometimes required.
To create a Queue- or TopicConnectionFactory, perform the following statements:
import com.swiftmq.jms.*;
...
Map props = new HashMap();
props.put(SwiftMQConnectionFactory.SOCKETFACTORY, "com.swiftmq.net.JSSESocketFactory");
props.put(SwiftMQConnectionFactory.HOSTNAME, "localhost");
props.put(SwiftMQConnectionFactory.PORT, "4001");
props.put(SwiftMQConnectionFactory.KEEPALIVEINTERVAL, "60000");
QueueConnectionFactory qcf = (QueueConnectionFactory) SwiftMQConnectionFactory.create(props);
TopicConnectionFactory tcf = (TopicConnectionFactory) SwiftMQConnectionFactory.create(props);
The Map parameter of the "create" method contains all necessary properties to create the required connection factory. The returned connection factory can be casted to both, Queue- and TopicConnectionFactory. The following table lists all possible properties which can be passed to the "create" method. All values have to be of String type.
| Property | Default | Meaning |
|---|---|---|
| SwiftMQConnectionFactory. SOCKETFACTORY | - | Name of the Socket Factory class. |
| SwiftMQConnectionFactory. HOSTNAME | - | Host Name. |
| SwiftMQConnectionFactory. PORT | - | Port. |
| SwiftMQConnectionFactory. RECONNECT_HOSTNAME2 | - | Host Name HA instance 2. Since 6.0.0. |
| SwiftMQConnectionFactory. RECONNECT_PORT2 | - | Port HA instance 2. Since 6.0.0. |
| SwiftMQConnectionFactory. KEEPALIVEINTERVAL | "0" | SMQP Keep Alive Interval |
| SwiftMQConnectionFactory. CLIENTID | null | Presets the JMS client id. If none is specified (default), a random client id is created. Note that it is not possible to create a durable subscriber without a client id or with a random one. The router will reject it. |
| SwiftMQConnectionFactory. SMQP_PRODUCER_REPLY_INTERVAL | "20" | Contains the interval after which a message producer waits on a reply and thus can act on flow control delays. This attributes takes only effect for non-persistent messages. The default value is optimal in conjunction with a smqp-consumer-cache-size of 500. |
| SwiftMQConnectionFactory. SMQP_CONSUMER_CACHE_SIZE | "500" | Contains the size of the client message cache of message consumers. The router sends up to this size without waiting for a reply. This attribute effects performance and the default value is optimal in conjunction with a smqp-producer-reply-interval of 20. |
| SwiftMQConnectionFactory. SMQP_CONSUMER_CACHE_SIZE_KB | "2048" | Limits the size of the cache per consumer to the specified value in KB. A value of -1 disables it. Limiting the size is useful to avoid out of memory errors if large messages are transfered. Since 7.5.0. |
| SwiftMQConnectionFactory. JMS_DELIVERY_MODE | String.valueOf(Message.DEFAULT_DELIVERY_MODE) | Presets the JMS default delivery mode for message producers. The default value is compliant with the JMS specification. |
| SwiftMQConnectionFactory. JMS_PRIORITY | String.valueOf(Message.DEFAULT_PRIORITY) | Presets the JMS default message priority for message producers. The default value is compliant with the JMS specification. |
| SwiftMQConnectionFactory. JMS_TTL | String.valueOf(Message.DEFAULT_TIME_TO_LIVE) | Presets the JMS default message time-to-live for message producers. The default value is compliant with the JMS specification. |
| SwiftMQConnectionFactory. JMS_MESSAGEID_ENABLED | "true" | Presets whether a message id should be generated for produced messages. The default value is compliant with the JMS specification. |
| SwiftMQConnectionFactory. JMS_TIMESTAMP_ENABLED | "true" | Presets whether a time stamp should be generated for produced messages. The default value is compliant with the JMS specification. |
| SwiftMQConnectionFactory. USE_THREAD_CONTEXT_CLASSLOADER | "false" | Presets whether the thread contex class loader should be used during the deserialization of objects returned from an ObjectMessage' getObject() method. This is important if SwiftMQ is integrated into app servers which use different class loaders for message-driven beans. |
| SwiftMQConnectionFactory. RECONNECT_ENABLED | "false" | Enables transparent reconnect for JMS clients. Since 6.0.0. |
| SwiftMQConnectionFactory. RECONNECT_MAX_RETRIES | 10 | Specifies the max. retries for reconnect attemts. Since 6.0.0. |
| SwiftMQConnectionFactory. RECONNECT_RETRY_DELAY | 10000 | Specifies the delay in ms between reconnect retries. Since 6.0.0. |
| SwiftMQConnectionFactory. DUPLICATE_DETECTION_ENABLED | "false" | Enables/disables duplicate message detection at the client side. Must be enabled if reconnect is enabled. Since 6.0.0. |
| SwiftMQConnectionFactory. DUPLICATE_BACKLOG_SIZE | 30000 | Specifies the max. size of the duplicate backlog per connection (JMS Message Ids) at the client side. Since 6.0.0. |
| SwiftMQConnectionFactory. INPUT_BUFFER_SIZE | "131072" | Specifies the initial size in bytes of the JMS client's network input buffer. |
| SwiftMQConnectionFactory. INPUT_EXTEND_SIZE | "65536" | Specifies the extend size in bytes to increase the JMS client's network input buffer once it is full. |
| SwiftMQConnectionFactory. OUTPUT_BUFFER_SIZE | "131072" | Specifies the initial size in bytes of the JMS client's network output buffer. |
| SwiftMQConnectionFactory. OUTPUT_EXTEND_SIZE | "65536" | Specifies the extend size in bytes to increase the JMS client's network output buffer once it is full. |