WebSphere WebSphere Application Server Network Deployment, Version 6.0.x Operating Systems: AIX, HP-UX, Linux, Solaris, Windows

JMS connection factory settings

A JMS connection factory is used to create connections to the associated JMS provider of JMS destinations, for both point-to-point and publish/subscribe messaging. Use connection factory administrative objects to manage JMS connection factories for the default messaging provider.

In the administrative console page, to view this page click JMS providers > Default messaging provider > JMS connection factories > [Content Pane] factory_name.

Use this panel to browse or change the configuration properties of the selected JMS connection factory for use with the default messaging JMS provider. These configuration properties control how connections are created to associated JMS queues and topics.

By default, connections created using this JMS connection factory in the server containers (for example, from an enterprise bean) are pooled using J2C connection pooling. You can modify the connection pool settings for this connection factory by selecting the Connection pool properties link in the Additional properties section of the administrative console panel.

The configuration of a container-managed authentication alias and mapping module on a connection factory are deprecated in release 6.0. You now set these properties in the bindings for the resource reference of the application. If you do not want to modify the bindings for an existing application, locate this connection factory in the J2C panels where you can still find these properties.

Related concepts
JMS connection factories and service integration
Related tasks
Configuring a unified JMS connection factory for the default messaging provider
Related reference
Creating a new JMS connection factory using the wsadmin tool
Modifying an existing JMS connection factory using the wsadmin tool

Configuration tab

Configuration properties for this object. These property values are preserved even if the runtime environment is stopped then restarted. See the information center task descriptions for information about how to apply configuration changes to the runtime environment.

General properties

Scope

The level to which this resource definition is visible; for example, the cell, node, cluster, or server level.

The scope displayed is for information only, and cannot be changed on this panel. If you want to browse or change this resource (or other resources) at a different scope, change the scope on the messaging provider settings panel, then click Apply, before clicking the link for the type of resource.

Required Yes
Data type Text

Name

The name by which this resource is known for administrative purposes.

Required Yes
Data type Text

JNDI name

The JNDI name for the resource.

As a convention, use a JNDI name of the form jms/Name, where Name is the logical name of the resource. For more information about the use of JNDI and its syntax, see JNDI support in WebSphere Application Server.

Required Yes
Data type Text

Description

An optional description for the resource.

Required No
Data type Text area

Category

An optional category string to use when classifying or grouping the resource.

Required No
Data type Text

Bus name

The name of the service integration bus to connect to.

This is the name of the service integration bus that this connection factory is used to create connections to.
Required Yes
Data type Custom

Client identifier

The JMS client identifier needed for durable topic subscriptions on all connections created using this connection factory.

If an application that uses this connection factory wants to use durable subscriptions, the client identifier must be set. If the application does not set the client identifier programmatically, the value set on this administrative property is used.

The preferred way to assign a client identifier is for it to be configured on the connection factory and transparently assigned to connections that the factory creates. Alternatively, an application can set the client identifier immediately after creating the connection.

For more information about the use of client identifiers, see the "Client identifiers" section of the JMS Specification.

Required No
Data type Text

Nonpersistent message reliability

The reliability applied to nonpersistent JMS messages sent using this connection factory.

If you want different reliability delivery options for individual JMS destinations, you can set this property to As bus destination. The reliability is then defined by the Reliability property of the bus destination that the JMS destination is assigned to.
Required No
Data type Selection list
Default Express nonpersistent
Range
Best effort nonpersistent
Messages are discarded when a messaging engine stops or fails. Messages may also be discarded if a connection used to send them becomes unavailable and as a result of constrained system resources.

Express nonpersistent
Messages are discarded when a messaging engine stops or fails. Messages may also be discarded if a connection used to send them becomes unavailable.

Reliable nonpersistent
Messages are discarded when a messaging engine stops or fails.

Reliable persistent
Messages may be discarded when a messaging engine fails.

Assured persistent
Messages are not discarded.

As bus destination
Use the delivery option configured for the bus destination.

Read ahead

Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests.

Messages that are assigned to a consumer are locked on the server and cannot be consumed by any other consumers for that destination. Messages that are assigned to a consumer, but not consumed before that consumer is closed, are subsequently unlocked on the server and then available for receipt by other consumers.

You can override this property for individual JMS destinations by setting the Read ahead property on the JMS destination.

Required No
Data type Selection list
Default Default
Range
Default
The message provider preemptively assigns messages to consumers on nondurable subscriptions and unshared durable subscriptions. That is, read ahead optimization is turned on only when there can only be a single consumer.

Enabled
The messaging provider preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests.

You may not want to select this option if you have multiple clients attempting to receive from the same destination, because it can adversely affect message processing. For example, you allocate five messages to client A, but client A takes a long time processing the first of those messages. Meanwhile client B is available, but doing nothing, and could have been helping out with the other four messages. So, the "Default" behavior is to only have it on when there can only be one client (that is, for nondurable subscriptions and durable subscriptions in a non-clustered environment). However, if you are using a queue but you know that there is only ever one client attached to that queue at any one time, you could override the default behavior by selecting this option.

Disabled
The messaging provider does not preemptively assign messages to consumers.

Temporary queue name prefix

The prefix of up to twelve characters used for names of temporary queues created by applications that use this connection factory.

This property is for administrative purposes; for example, to enable filtering of temporary queue names.

The default for this property is null, which causes temporary queues to be named without any prefix.

Required No
Data type Text

Temporary topic name prefix

The prefix of up to twelve characters used for names of temporary topics created by applications that use this connection factory.

This property is for administrative purposes; for example, to enable filtering of temporary topic names
Temporary topic names are created with the leading characters "_T" followed by this topic prefix then a system-assigned value.
_T<topic_prefix>_<messaging_engine_id><destination_id>
Where
<topic_prefix>
is the value specified on this property.
<messaging_engine_id>
is a 16-character identifier for the messaging engine to which the temporary topic is assigned.
<destination_id>
is a 16-character identifier assigned to the temporary topic.

If the topic is to be used with WebSphere MQ, the topic prefix value should be a maximum of 12 characters.

The default for this property is null, which causes temporary topics to be named without any prefix.

Required No
Data type Text
Default Null

Durable subscription home

The name of the messaging engine used to store messages delivered to durable subscriptions for objects created from this JMS connection factory.

To enable applications to use durable subscriptions, you must set this property.
Required No
Data type Text
Default Null

Share durable subscriptions

Controls whether or not durable subscriptions are shared across connections with members of a server cluster.

Normally, only one session at a time can have a TopicSubscriber for a particular durable subscription. This property enables you to override this behavior, to enable a durable subscription to have multiple simultaneous consumers.
Required No
Data type Selection list
Default In cluster
Range
In cluster
Allows sharing of durable subscriptions when connections are made from within a server cluster.

Always shared
Durable subscriptions can be shared across connections.

Never shared
Durable subscriptions are never shared across connections.

Target

The name of a target that identifies a group of messaging engines. Specify the type of target using the Target type property.

This indicates the name of one of the following types of targets, as indicated by the Target type property

Connections are load balanced across the available messaging engines that satisfy the selection criteria.

If want applications to be able to connect to any messaging engine in the bus, do not set this property.
Required No
Data type Text

Target type

The type of target named in the Target property.

Required No
Data type Selection list
Range
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 specifies the significance of the target group.

Required No
Data type Selection list
Default Preferred
Range
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.

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.

Target inbound transport chain

The name of the protocol that resolves to a group of messaging engines.

Type the name of the transport chain that the application should use when connecting to a messaging engine in separate process to the application. If a messaging engine in another process is chosen, a connection can be made only if the messaging engine is in a server that runs the specified transport chain.

If the selected messaging engine is in the same server as the application, a direct in-process connection is made and this transport chain property is ignored.

The transport chains represent network protocol stacks operating within a server. The name you specify must be one of the transport chains available in the server that hosts the messaging engine, as listed on the Servers > Application servers > server > Messaging engine inbound transports panel. The following transport chains are provided, but you can define your own transport chains on that panel.

InboundBasicMessaging
This is a connection-oriented protocol, using a standard TCP/IP connection (JFAP-TCP/IP). It includes support for two-phase transactional (remote XA) flows, so that a message producer or consumer, running on a client or server system, can participate in a global transaction managed on that client or server system. The specific use for the XA flows is to support access from an application running in one server to a messaging engine on second server, perhaps because the first server does not have a suitable messaging engine. If the remote XA flows are used, a transaction coordinator must be available local to the application.
InboundSecureMessaging
This is the InboundBasicMessaging protocol wrapped in SSL.
Required No
Data type Text
Default Null

Provider endpoints

The list of comma separated endpoints used to connect to a bootstrap server.

You only need to specify provider endpoints if the connection factory is used by client applications running outside of a server environment or is used by an application running on a server in one cell to connect to a target bus in another cell.
In these scenarios, the clients (or servers in another bus) cannot locate directly a suitable messaging engine to connect to in the target bus. The client must locate a suitable messaging engine by first using a bootstrap server running a SIB Service (see Servers > Application servers > server_name > SIB Service). The bootstrap server locates a suitable messaging engine on behalf of the client then tells the client how to connect to the selected messaging engine. When using a bootstrap server, one of the predefined bootstrap transport chains must be specified. The predefined bootstrap transport chains are:
BootstrapBasicMessaging
This corresponds to the server transport chain InboundBasicMessaging (JFAP-TCP/IP)
BootstrapSecureMessaging
This corresponds to the server transport chain InboundSecureMessaging (JFAP-SSL-TCP/IP)
BootstrapTunneledMessaging
Before you can use this bootstrap transport chain, you must define a corresponding server transport chain on the bootstrap server. (See Servers > Application servers > server_name > Messaging engine inbound transports.) This transport chain tunnels JFAP using HTTP wrappers.
BootstrapTunneledSecureMessaging
Before you can use this bootstrap transport chain, you must define a corresponding server transport chain on the bootstrap server. (See Servers > Application servers > server_name > Messaging engine inbound transports.) This transport chain tunnels JFAP using HTTP wrappers.

To specify endpoint addresses, type a comma-separated list of endpoint triplets, each of the form host_name:port_number:chain_name where:

host_name
is the name of the host on which the bootstrap server runs. It can be an IP address. In the case of an IPv6 address, put square braces ([]) around host_name as shown in the example below:
[2002:914:fc12:179:9:20:141:42]:7276:BootstrapBasicMessaging
If host_name is not specified, the default is localhost.
port_number
is the number of the port on which the bootstrap server listens. If not specified, the default is 7276.
chain_name
is the name of a predefined bootstrap transport chain used to connect to the bootstrap server. If not specified, the default is BootstrapBasicMessaging.
If you do not specify any endpoint value, the connection factory uses the default endpoint address:
localhost:7276:BootstrapBasicMessaging

You can create other transport chains and specify them as part of the provider endpoints.

Required No
Data type Text area

Connection proximity

The proximity of messaging engines that can accept connection requests, in relation to the bootstrap messaging engine.

When a client issues a client connect request, the processing attaches to the required bus according to the following logic:
  • If a target group is specified, connect to the first messaging engine that satisfies the following conditions for the target type:
    • Server Look for a messaging engine in the same server.
    • Cluster Look for a messaging engine in the same server, then on other servers in the same cluster.
    • Host Look for a messaging engine in the same server, then on other servers in the same cluster, then on other servers in the same host.
    • Bus Look for a messaging engine in the same server, then on other servers in the same cluster, then on other servers in same host, then any other messaging engine on the same bus.
  • If a target group is not specified, or a target group is specified but no suitable messaging engine is found and target significance is Preferred, connect to the first messaging engine that satisfies the following conditions for the target type:
    • Server Look for a messaging engine in the same server.
    • Cluster Connection fails.
    • Host Look for a messaging engine in the same server, then on other servers in the same host.
    • Bus Look for a messaging engine in the target group in same server, then on other servers in same host, then any other messaging engine on the same bus.
Required No
Data type Selection list
Default Bus
Range
Bus
Connections can be made to messaging engines in the same bus.

Cluster
Connections can be made to messaging engines in the same server cluster.

Host
Connections can be made to messaging engines in the same host.

Server
Connections can be made to messaging engines in the same application server.

Component-managed authentication alias

This alias specifies a user ID and password to be used to authenticate connections to the JMS provider for application-managed authentication.

This property provides a list of the J2C authentication data entry aliases that have been defined to WebSphere Application Server. You can select a data entry alias to be used to authenticate the creation of a new connection to the JMS provider.

If you have enabled global security for WebSphere Application Server, select the alias that specifies the user ID and password used to authenticate the creation of a new connection to the JMS provider. The use of this alias depends on the resource authentication (res-auth) setting declared in the connection factory resource reference of an application component's deployment descriptors.

Required No
Data type Selection list

Log missing transaction contexts

Whether or not the container logs that there is a missing transaction context when a connection is obtained.

The J2EE programming model indicates that connections should always have a transaction context. However, some applications do not correctly have a transaction context associated with them.

Select this property to log connections being created without a transaction context.

Required No
Data type Check box
Default Cleared

Manage cached handles

Whether cached handles (handles held in instance variables in a bean) should be tracked by the container.

Select this option to track handle management, which can be useful for debugging purposes. However, tracking handles can cause large performance overhead if used at run time.
Required No
Data type Check box
Default Cleared

Share data source with CMP

Allow sharing of connections between JMS and container-managed persistence (CMP) entity beans.

This option is used as part of the task to enable container-managed persistence (CMP) entity beans to share the database connections used by the data store of a messaging engine. This has been estimated as a potential performance improvement of 15% for overall message throughput, but can only be used for entity beans connected to the application server that contains the messaging engine.

For more information about using this option, see Enabling CMP entity beans and messaging engine data stores to share database connections.

Required No
Data type Check box
Default Cleared

XA recovery authentication alias

The authentication alias used during XA recovery processing.

Select the alias to be used during transaction recovery processing.

This property provides a list of the J2C authentication data entry aliases that have been defined to WebSphere Application Server. You can select a data entry alias to be used to authenticate during XA recovery processing.

If you have enabled security for the associated service integration bus, select the alias that specifies the user ID and password used for XA recovery. This property must be set if bus security is enabled and XA transactions are to be used.

Required No
Data type Selection list

Persistent message reliability

The reliability applied to persistent JMS messages sent using this connection factory.

If you want different reliability delivery options for individual JMS destinations, you can set this property to As bus destination. The reliability is then defined by the Reliability property of the bus destination that the JMS destination is assigned to.
Required No
Data type Selection list
Default Reliable persistent
Range
Best effort nonpersistent
Messages are discarded when a messaging engine stops or fails. Messages may also be discarded if a connection used to send them becomes unavailable and as a result of constrained system resources.

Express nonpersistent
Messages are discarded when a messaging engine stops or fails. Messages may also be discarded if a connection used to send them becomes unavailable.

Reliable nonpersistent
Messages are discarded when a messaging engine stops or fails.

Reliable persistent
Messages may be discarded when a messaging engine fails.

Assured persistent
Messages are not discarded.

As bus destination
Use the delivery option configured for the bus destination.

Additional properties

Connection pool
An optional set of connection pool settings.

Reference topic

Terms of Use | Feedback

Last updated: 15 Mar 2007
http://publib.boulder.ibm.com/infocenter/wasinfo/v6r0/index.jsp?topic=/com.ibm.websphere.pmc.nd.doc\sibjmsresources\SIBJMSConnectionFactory_DetailForm.html

© Copyright IBM Corporation 2004, 2007. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)