Default messaging provider unified 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 admin objects to manage JMS connection factories for the default messaging provider.

To view this page in the console, click one of the following paths:

• Resources | JMS | Connection factories | factory_name

• Resources | JMS | JMS providers | a_messaging_provider | [Additional Properties] Connection factories | factory_name

Set, browse or change the configuration properties of a 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 by using this JMS connection factory in the server containers (for example, from an enterprise bean) are pooled by using Java EE Connector Architecture (JCA) connection pooling. We can modify the connection pool settings for this connection factory by selecting the Connection pool properties link in the Additional properties section of the admin console panel.

The connection factory properties influence how the default messaging provider chooses the messaging engine to which the JMS application connects. By default, the environment automatically connects applications to an available messaging engine on the bus. However we can specify extra configuration details to influence the connection process; for example to...

• identify special bootstrap servers
• limit connection to a subgroup of available messaging engines
• improve availability or performance
• ensure sequential processing of messages received

 

Configuration tab

The Configuration tab shows configuration properties for this object. These property values are preserved even if the runtime environment is stopped then restarted.

 

General Properties

Scope

Specifies the highest topological level at which appservers can use this resource object.

Required	No
Data type	Text

 

Provider

Specifies a JMS provider, which enables asynchronous messaging based on the JMS. It provides J2EE connection factories to create connections for specific JMS queue or topic destinations. JMS provider admin objects are used to manage JMS resources for the associated JMS provider.

Required	No
Data type	Text

 

Name

The required display name for the resource.

Required	Yes
Data type	Text

 

JNDI name

The JNDI name for the resource.

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.

Enter the name of the local bus in situations where an application makes connection to foreign buses.

Required	Yes
Data type	Custom

 

Target

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

Before the connection proximity search is performed to select a suitable messaging engine, 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 property specifies the name of the bus member from which suitable messaging engines can be chosen.

Required	No
Data type	Text

 

Target type

The type of target named in the Target property.

Required	No
Data type	drop-down 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 appserver or server cluster). To specify a non-clustered bus member the Target property must be set to <Node01>.<server1>, for example Node01.server1. For a cluster bus member the Target property must be set to the cluster name. 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.

This property defines whether the connection proximity search is restricted to only the messaging engines in the target group.

Required	No
Data type	drop-down list
Range	Preferred It is preferred that a messaging engine is 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. A connection to a non-preferred target might 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 you use 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 receives this pooled connection even if the preferred messaging engine has subsequently become available. We can modify the connection pool settings to regularly discard all unused connections in the pool. After the connection pool is emptied, connections are 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 refreshes the connection pool every 5 minutes, after which time the application selects a preferred messaging engine if one is available. Required It is required that a messaging engine is 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 inbound transport chain that the application should target when connecting to a messaging engine in a 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 inbound transport chain.

These transport chains specify the communication protocols that can be used to communicate with the appserver to which the client application is connected.

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 specified must be one of the transport chains available in the server that hosts the messaging engine, as listed on the panel...

Servers | Server Types | WebSphere application servers | server_name | [Server messaging] Messaging engine inbound transports

The following transport chains are provided, but we can define our own transport chains on that panel.

InboundBasicMessaging

This is a connection-oriented protocol that uses 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.

See about using this property with other connection factory properties for workload management of connections, see Administrative properties for JMS connections to a bus.

Required	No
Data type	Text

 

Provider endpoints

A comma-separated list of endpoint triplets, with the syntax...

hostName:portNumber:chainName

...used to connect to a bootstrap server. For example...

Merlin:7276:BootstrapBasicMessaging,Gandalf:5557:BootstrapSecureMessaging

If hostName is not specified, the default is localhost. If portNumber is not specified, the default is 7276. If chainName is not specified, the default is BootstrapBasicMessaging.

We only have to modify this property if we have client applications running outside of an application server, or applications on a server in another cell, that want to use this connection factory to connect to the target service integration bus specified on the connection factory. To use JMS destinations of the default messaging provider, an application connects to a messaging engine on the target 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.

Client applications running outside of an appserver - for example, running in a client container or outside the WAS environment - cannot locate directly a suitable messaging engine to connect to in the target bus. Similarly, an application running on a server in one cell to connect to a target bus in another cell cannot locate directly a suitable messaging engine to connect to in the target bus.

In these scenarios, the clients (or servers in another bus) must complete a bootstrap process through a bootstrap server that is a member of the target bus. A bootstrap server is an appserver running the SIB Service, but does not have to be running any messaging engines. The bootstrap server selects a messaging engine that is running in an appserver that supports the required target transport chain. For the bootstrap process to be possible, configure one or more provider end points in the connection factory used by the client.

A bootstrap server uses a specific port and bootstrap transport chain. The port is the...

SIB_ENDPOINT_ADDRESS

...or if security is enabled...

SIB_ENDPOINT_SECURE_ADDRESS

...of the messaging engine that hosts the remote end of the link. Together with host name, these form the endpoint address of the bootstrap server.

The properties of a JMS connection factory used by an application control the selection of a suitable messaging engine and how the application connects to the selected messaging engine.

• If no security credentials are provided, then by default

  • If no host is specified then localhost is used

  • If no port is specified then port 7276 is used

  • If no bootstrap channel chain is specified then bootstrap transport chain called BootstrapBasicMessaging is used

• If security credentials are provided, then by default

  • If no host is specified then localhost is used

  • If no port is specified then port 7286 is used

  • If no bootstrap channel chain is specified then bootstrap transport chain called BootstrapBasicMessaging is used

If you want an application to use a bootstrap server with a different endpoint address, specify the required endpoint address on the Provider endpoints property of the JMS connection factories that the client application uses. We can specify one or more endpoint addresses of bootstrap servers.

The endpoint addresses for bootstrap servers must be specified in every JMS connection factory that is used by applications outside of an appserver. To avoid having to specify a long list of bootstrap servers, we can provide a few highly-available servers as dedicated bootstrap servers. Then you only have to specify a short list of bootstrap servers on each connection factory.

When configuring a connection to a non-default bootstrap server, specify the required values for the endpoint address and use colons as separators.

For example: for a server assigned non-secure port 7278, on host boothost1, that uses the default transport chain BootstrapBasicMessaging:

boothost1:7278:BootstrapBasicMessaging

...or...

boothost1:7278

...and for a server assigned secure port 7289, on host boothost2, that uses the predefined transport chain BootstrapTunneledSecureMessaging:

boothost2:7289:BootstrapTunneledSecureMessaging

The syntax for an endpoint address is as follows:

[ [host_name] [ ":" [port_number] [ ":" chain_name] ] ]

where:

host_name

is the name of the host on which the server runs. It can be an IP address. For 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 a value is not specified, the default is localhost.

port_number

...where specified, is one of the following addresses of the messaging engine that hosts the remote end of the link:

• SIB_ENDPOINT_ADDRESS if security is not enabled

• For secure connections, SIB_ENDPOINT_SECURE_ADDRESS if security is enabled.

If port_number is not specified, the default is 7276. To find either of these values by using the admin console, click...

Servers | Server Types | WebSphere application servers | server_name | [Communications] Ports

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.

The following predefined bootstrap transport chains are provided:

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 we can use this bootstrap transport chain, define a corresponding server transport chain on the bootstrap server. See...

Servers | Server Types | WebSphere application servers | server_name | [Server messaging] Messaging engine inbound transports

This transport chain tunnels JFAP and uses HTTP wrappers.

BootstrapTunneledSecureMessaging

Before we can use this bootstrap transport chain, define a corresponding server transport chain on the bootstrap server. See...

Servers | Server Types | WebSphere application servers | server_name | [Server messaging] Messaging engine inbound transports

This transport chain tunnels JFAP and uses HTTP wrappers.

Specifying...

host_name : chain_name instead of host_name : : chain_name

...with two colons is incorrect. It is valid to enter nothing, or to enter any of the following:

"a", "a:", ":7276", "::chain"

...and so on. The default value applies if you do not specify a value, but separate the fields with ":"s.

To provide more than one bootstrap server, identify all the required endpoint addresses. Separate each endpoint address by a comma character. For example, to use the servers from the earlier example:

boothost1:7278:BootstrapBasicMessaging, boothost2:7289:BootstrapTunneledSecureMessaging, [2002:914:fc12:179:9:20:141:42]:7276:BootstrapBasicMessaging

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.

See about using this property with other connection factory properties for workload management of connections, see Administrative properties for JMS connections to a bus.

Required	No
Data type	drop-down list
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 appserver.

 

Client identifier

The JMS client identifier needed for durable topic subscriptions on all connections created using this connection factory. This identifier is required if the application is doing durable pub/sub

Required	No
Data type	Text

 

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.

Required	No
Data type	Custom

 

Nonpersistent message reliability

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

We can change the delivery reliability option for the destination of a message that is sent by a JMS application as Nonpersistent. The default is Express nonpersistent but we have a range of other options, including those with persistent characteristics, with Assured persistent being the most reliable.

See see Message reliability levels - JMS delivery mode and service integration quality of service.

Required	No
Data type	drop-down list
Range	Best effort nonpersistent Messages are discarded when a messaging engine stops or fails. Messages might also be discarded if a connection used to send them becomes unavailable or as a result of constrained system resources. Express nonpersistent Messages are discarded when a messaging engine stops or fails. Messages might 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 might 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.

 

Persistent message reliability

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

We can change the delivery reliability option for the destination of a message that is sent by a JMS application as Persistent. The default is Reliable persistent but we have a range of other options including those with nonpersistent characteristics, with Best effort nonpersistent being the least reliable.

If you change the delivery reliability options of a message sent by a JMS application from one of the Persistent message reliability options (Assured persistent and Reliable persistent) to one of the Nonpersistent message reliability options (Best effort nonpersistent, Express nonpersistent, and Reliable nonpersistent), you risk losing messages in certain circumstances. For example, at server restart, or when there is heavy workload.

Required	No
Data type	drop-down list
Range	Best effort nonpersistent Messages are discarded when a messaging engine stops or fails. Messages might also be discarded if a connection used to send them becomes unavailable or as a result of constrained system resources. Express nonpersistent Messages are discarded when a messaging engine stops or fails. Messages might 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 might 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.

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

Required	No
Data type	drop-down list
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. 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.

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.

Required	No
Data type	Text

 

Share durable subscriptions

Controls whether or not durable subscriptions are shared across connections with members of a server cluster. Usually, 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	drop-down list
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.

 

Pass message payload by reference

When large object messages or bytes messages are sent, the cost in memory and processor use of serializing, deserializing, and copying the message payload can be significant. If you enable the pass message payload by reference properties on a connection factory or activation specification, you tell the default messaging provider to override the JMS 1.1 spec and potentially reduce or bypass this data copying.

The parts of the JMS Specification that are bypassed by these properties are defined to ensure message data integrity. Any of the JMS applications that use these properties must strictly follow the rules that are described in Why and when to pass the JMS message payload by reference, or you risk losing data integrity.

 

Applications that use this connection factory to send messages must obey the following rules:

• The application does not modify the data object contained in a JMS object message.

• The application populates a JMS bytes message by using a single call to writeBytes(byte[]) and does not modify the byte array after it is set in the message.

When enabled, Object/Bytes Messages sent by a message producing application that has connected to the bus using this connection factory will not have their data copied when set and the system will only serialize the message data when absolutely necessary. Applications sending such messages must not modify the data once it has been set into the message.

Required	No
Data type	Check box

 

Applications that use this connection factory to receive messages must obey the following rule:

• The application does not modify the data object obtained from a JMS object message. The data object is treated as read only.

When enabled, Object Messages received by a message consuming application that has connected to this connection factory will only have their message data serialized by the system when absolutely necessary. The data obtained from these messages must be treated as readOnly by applications.

Required	No
Data type	Check box

 

Log missing transaction contexts

Whether or not the container logs that there is a missing transaction context when a connection is obtained. The Java EE 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

 

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 significantly reduce performance if used at run time.

Required	No
Data type	Check box

 

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 appserver that contains the messaging engine.

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

Required	No
Data type	Check box

 

Authentication alias for XA recovery

Alias that the connection factory uses to authenticate with the EIS for transaction recovery.

Select the alias to be used during transaction recovery processing.

This property provides a list of the JCA authentication data entry aliases that have been defined to WAS. We can select a data entry alias to be used to authenticate during XA recovery processing.

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

Required	No
Data type	drop-down list

 

Mapping-configuration alias

Mapping configuration alias for the Java Authentication and Authorization Service (JAAS) mapping configuration that is used by this connection factory.

This field will be used only in the absence of a loginConfiguration on the component resource reference. The spec of a login configuration and associated properties on the component resource reference determines the container-managed authentication strategy when the res-auth value is Container.If the DefaultPrincipalMapping login configuration is specified, the associated property will be a JAAS - J2C authentication data entry alias. See related item JAAS - J2C authentication data entry to define a new alias.

Required	No
Data type	drop-down list

Container-managed authentication alias

This alias specifies a user ID and password to be used to authenticate connections to the JMS provider for container-managed authentication. This setting is only used when the res-auth value is container, and the authentication alias was not set when the application was deployed.

Required	No
Data type	drop-down list

 

Additional Properties

Connection pool properties

An optional set of connection pool settings.

 

Related Items

JAAS - J2C authentication data

List of user identities and passwords for Java 2 connector security to use.

Buses

A service integration bus supports applications using message-based and service-oriented architectures. A bus is a group of interconnected servers and clusters that have been added as members of the bus. Applications connect to a bus at one of the messaging engines associated with its bus members.