Red Hat Training

A Red Hat training course is available for JBoss Enterprise Application Platform Common Criteria Certification

5.8. Configuring Connection Factories

JBoss Messaging is configured by default to bind two connection factories in JNDI upon startup.
The first connection factory is the default, non-clustered connection factory. This connection factory is provided to maintain compatibility with applications originally written against JBossMQ, which does not include automatic failover or load balancing. If you do not require client-side automatic failover or load balancing, then you should use this first connection factory.
The first connection factory is bound into the following JNDI contexts:
  • /ConnectionFactory
  • /XAConnectionFactory
  • java:/ConnectionFactory
  • java:/XAConnectionFactory.
The second connection factory is the default clustered connection factory, which is bound into the following JNDI contexts:
  • /ClusteredConnectionFactory
  • /ClusteredXAConnectionFactory
  • java:/ClusteredConnectionFactory
  • java:/ClusteredXAConnectionFactory
If you want to provide a default client ID for a connection factory, or bind a connection factory to a different JNDI locationConsider, then configure and deploy additional connection factories. To deploy a new connection factory, configure a new ConnectionFactory managed bean in connection-factories-service.xml.
You can also create a new service deployment descriptor, <name>-service.xml, and deploy it in $JBOSS_HOME/server/messaging/deploy.
Enable support for automatic failover or load balancing by setting the relevant attributes in your connection factory:

Example 5.1. Connection Factory

This example connection factory creates a connection factory with the preconfigured client ID myClientID, which is bound to two locations in the JNDI tree: /MyConnectionFactory and /factories/cf.
The example overrides the following default values:
  • PreFetchSize
  • DefaultTempQueueFullSize
  • DefaultTempQueuePageSize
  • DefaultTempQueueDownCacheSize
  • DupsOKBatchSize
  • SupportsFailover
  • SupportsLoadBalancing
  • LoadBalancingFactory
The connection factory uses the default remoting connector. To use a different remoting connector with the connection factory, change the Connector attribute to specify the service name of the connector you wish to use. 
<mbean code="org.jboss.jms.server.connectionfactory.ConnectionFactory"
  name="jboss.messaging.connectionfactory:service=MyConnectionFactory"
  xmbean-dd="xmdesc/ConnectionFactory-xmbean.xml">
  <depends optional-attribute-name="ServerPeer">
    jboss.messaging:service=ServerPeer
  </depends>
  <depends optional-attribute-name="Connector">
    jboss.messaging:service=Connector,transport=bisocket
  </depends>
  <depends>jboss.messaging:service=PostOffice</depends>

  <attribute name="JNDIBindings">
    <bindings>
    <binding>/MyConnectionFactory</binding>
    <binding>/factories/cf</binding>
    </bindings>
  </attribute>
  
  <attribute name="ClientID">myClientID</attribute>

  <attribute name="SupportsFailover">true</attribute>
  
  <attribute name="SupportsLoadBalancing">false</attribute>  
  
  <attribute name="LoadBalancingFactory">
    org.acme.MyLoadBalancingFactory
  </attribute>
      
  <attribute name="PrefetchSize">1000</attribute> 

  <attribute name="SlowConsumers">false</attribute>
  
  <attribute name="StrictTck">true</attribute>
  
  <attribute name="SendAcksAsync">false</attribute>

  <attribute name="DefaultTempQueueFullSize">50000</attribute>
  
  <attribute name="DefaultTempQueuePageSize">1000</attribute> 
    
  <attribute name="DefaultTempQueueDownCacheSize">1000</attribute> 
  
  <attribute name="DupsOKBatchSize">10000</attribute> 
</mbean>

5.8.1. ConnectionFactory Managed Bean Attributes

ClientID
You can preconfigure a connection factory with a client ID. Any connection created via this connection factory will obtain this client ID.
JNDIBindings
Lists available JNDI bindings for this connection factory.
PrefetchSize
Specifies how many messages the window holds at once, for consumer flow control. The window size determines the number of messages a server can send to a consumer without blocking. Each consumer maintains a buffer of messages from which it consumes.
Transmission Control Protocol (TCP) implements its own additional flow control. Message consumption can also be blocked if the TCP window size is smaller than the PrefetchSize parameter.
SlowConsumers
Specifies whether the allowable buffer size for slow consumers is reduced. Reducing the buffer size for slow consumers results in minimized to increase the potential for messages to be consumed by faster consumers. It is not possible to totally disable buffering, however, setting the SlowConsumers attribute to true will reduce the buffer size. Setting this attribute to true is equivalent to setting PrefetchSize to 1 which is the lowest possible value available.
StrictTck
Enables strict JMS behavior if the attribute is set to true. Strict JMS behavior is required by the Technology Compatibility Kit (TCK).
SendAcksAsync
Specifies acknowledgments are sent asynchronously if the attribute is set to true. This can improve performance, particularly if auto_acknowledge mode is active.
DefaultTempQueueFullSize
Optional attribute that specifies the paging parameters for temporary full size queue destinations, which are scoped to connections created with this connection factory. The default value is 200000. For more information about these attributes, refer to Section 5.7.3.1.2, “Destination paging parameters”.
DefaultTempQueuePageSize
Optional attribute that specifies the paging parameters for temporary page size destinations, which are scoped to connections created with this connection factory. The default value is 2000. For more information about these attributes, refer to Section 5.7.3.1.2, “Destination paging parameters”.
DefaultTempQueueDownCacheSize
Optional attribute that specifies the paging parameters for temporary down cache size destinations, which are scoped to connections created with this connection factory. The default value is 2000. For more information about these attributes, refer to Section 5.7.3.1.2, “Destination paging parameters”.
DupsOKBatchSize
Specifies the number of DUPS_OK_ACKNOWLEDGE acknowledgments that are buffered locally before they are sent. The default value is 2000.
SupportsLoadBalancing
Specifies whether client-side load balancing is enabled for the connection factory on clustered installations. If load balancing is enabled, any connection created by that connection factory will be load-balanced across the nodes of a cluster. A connection created on a particular node remains on that node. The default value is false.
SupportsFailover
Specifies whether client-side automatic failover is enabled for the connection factory on clustered installations. If automatic failover is enabled, JBoss Messaging will automatically and transparently failover to another node in the cluster when a connection problem is detected. The default value is false.

Note

When automatic failover is disabled, the user code is responsible for catching connection exceptions in synchronous JMS operations, and a JMS ExceptionListener must be installed to catch exceptions asynchronously. When an exception is caught, the client-side code must lookup a new connection factory via HAJNDI and recreate the connection.
DisableRemotingChecks
Specifies whether the connection factory checks that the corresponding JBoss Remoting Connector uses sensible values. JBoss Messaging is very sensitive to these values, and there is rarely any need to change them. To disable this sanity checking, set DisableRemotingChecks to false. The default value is true.

Warning

Do not disable the remoting checks; system instability.
LoadBalancingFactory
Specifies the client-side load balancing factory implementation used by the connection factory. The value must correspond to the name of a class that implements the interface org.jboss.jms.client.plugin.LoadBalancingFactory.
The default value is org.jboss.jms.client.plugin.RoundRobinLoadBalancingFactory, which load-balances connections across the cluster in a round-robin fashion.
Connector
Specifies the remoting connector used by the connection factory. Different connection factories can use different connectors, so you can deploy one connection factory that uses the HTTP transport to communicate with the server, and another that uses the bisocket transport to communicate.
EnableOrderingGroup
Specifies whether strict message ordering is enabled on the ConnectionFactory. If set to true, any messages sent from producers which are created from the enabled connection factory become ordering group messages. The default value for this parameter is false.
DefaultOrderingGroupName
Specifies the default name for the message ordering group. The specified name will take effect once the EnableOrderingGroup parameter is set to true . If this attribute is missing, the group name will be generated automatically.