Use this task to configure the JMS connection factory that an application uses, to tailor the process used to select a messaging engine for the application to connect to.
Why and when to perform this task
To use JMS destinations of the default messaging provider, a client application connects to a messaging engine on the service integration bus to which the destinations are assigned. For example, a JMS queue is assigned to a queue destination on a service integration bus.
The selection process is used to choose a messaging engine that an application should connect to. The default configuration enables applications to connect to any available messaging engine in the bus. For this configuration, you only need to specify the one required connection property, Bus name, which sets the name of the bus to which the application wants to connect.
The information that controls the selection process is configured on the connection factory (or programmatically by the application). You can configure the properties of the connection factory to restrict the range of messaging engines that applications can connect to.
This task is based on an application that uses a unified JMS connection factory. You can use the same task to configure a JMS queue connection factory or JMS topic connection factory, but during the task would need to select the appropriate type of connection factory instead of JMS connection factory.
You can restrict the range of suitable messaging engines to a subgroup of those available in the service integration bus, by using the connection properties of the connection factory.
- Target inbound transport chain
- The messaging engine inbound transport chain that must be supported by the application server in which the messaging engine runs.
These transport chains specify the communication protocols that can be used to communicate with the application server that the client application is connected to. The following predefined messaging engine inbound transport chains are provided:
- InboundBasicMessaging
- JFAP over TCP/IP
- InboundSecureMessaging
- JFAP over SSL over TCP/IP
- Connection proximity
- Only messaging engines that are within the selected proximity setting can be chosen for applications to connect to.
For an application running in an application server, this property defines how close messaging engines must be to the application server. For an application running outside an application server, this property defines how close messaging engines must be to the bootstrap server.
When searching for the most suitable messaging engine a closer messaging engine is always selected ahead of a more remote messaging engine.
- Bus
- Connections can be made to messaging engines in the same bus.
A suitable messaging engine in the same server is selected ahead of a suitable messaging engine in the same host, and in turn ahead of a suitable messaging engine in another host.
- Cluster
- Connections can be made to messaging engines in the same server cluster. If the application is not running in a clustered server, or bootstrap server is not in a cluster, then there are no suitable messaging engines.
A suitable messaging engine in the same server is selected ahead of a suitable messaging engine in the same host, and in turn ahead of a suitable messaging engine in another host.
- Host
- Connections can be made to messaging engines in the same host. A suitable messaging engine in the same server is selected ahead of a suitable messaging engine in the same host.
- Server
- Connections can be made to messaging engines in the same application server.
- Target group
- The name of a target that resolves to a group of messaging engines on which the connection proximity check is applied to select a suitable messaging engine.
Before the connection proximity search is performed the set of messaging engines that are members of the specified target group are selected. The connection proximity search is then restricted to these messaging engines. If a target group is not specified (the default), then all messaging engines in the bus are considered during the connection proximity search.
For example, if the Target type property is set to Bus member name, the Target group specifies the name of the bus member from which suitable messaging engines can be chosen.
- Target type
- The type of target named in the Remote target group parameter; for example, if set to Bus member, the connection factory retrieves the active messaging engines in the named bus member.
- Bus member name
- The name of a bus member. This option retrieves the active messaging engines that are hosted by the named bus member (an application server or server cluster).
- Custom messaging engine group name
- The name of a custom group of messaging engines (that form a self-declaring cluster). This option retrieves the active messaging engines that have registered with the named custom group.
- Messaging engine name
- The name of a messaging engine. This option retrieves the available endpoints that can be used to reach the named messaging engine.
- Target significance
- This property defines whether or not the connection proximity search must be restricted to only the messaging engines in the target group.
- Preferred
- It is preferred that a messaging engine be selected from the target group. A messaging engine in the target group is selected if one is available. If a messaging engine is not available in the target group, a messaging engine outside the target group is selected if available in the same service integration bus.
Note: It is possible for a connection to a non-preferred target to be returned even if a preferred one is available. This can happen when connection pooling is enabled for a ConnectionFactory, which it is by default when using a JMS ConnectionFactory in a server environment.
When a preferred messaging engine is not available, a connection to a non-preferred one can be created, and stored in the connection pool. The next time the application requests a connection it will receive this pooled connection even if the preferred messaging engine has subsequently become available.
This can be resolved by modifying the Connection pool settings to regularly discard all unused connections in the pool. After the connection pool is emptied, connections will be made to the preferred messaging engine if one is available.
For example, set the ReapTime, AgedTimeout and UnusedTimeout to 300 seconds, and the PurgePolicy to EntirePool. This will refresh the connection pool every 5 minutes, after which time the application will select a preferred messaging engine if one is available.
- Required
- It is required that a messaging engine be selected from the target group. A messaging engine in the target group is selected if one is available. If a messaging engine is not available in the target group, the connection process fails.
To configure any of these properties of a connection factory, complete the following steps.
- If the client application uses a JMS connection factory in the client container, use the Client Resource Configuration tool (ACRCT) to configure the Provider endpoint property:
- Start the tool and open the EAR file for which you want to configure the JMS connection factory. The EAR file contents are displayed in a tree view.
- From the tree, select the JAR file in which you want to configure the JMS connection factory.
- Expand the JAR file to view its contents.
- Expand .
- Optional: Display the general properties of the connection factory:
- On the General tab, configure the connection properties.
- Click OK.
- To save your changes, click .
- If the client application uses a JMS connection factory on the server, use the WebSphere Application Server administrative console to configure the connection properties:
- Display the default messaging provider. In the navigation pane, expand .
This displays in the content pane a table of properties for the default messaging provider, including links to the types of JMS resources that it provides.
- Optional: Change the Scope check box to set the level at which the connection factory is to be visible, according to your needs.
- In the content pane, under Additional Properties, click JMS connection factory This displays any existing connection factories in the content pane.
- Optional: Display the general properties of the connection factory:
- Configure the connection properties.
- Click OK.
- Save your changes to the master configuration.