WebSphere MQ connection factory settings

 

+

Search Tips   |   Advanced Search

 

To set the configuration properties of the selected JMS connection factory for use with WebSphere MQ as a JMS provider.

1. In the navigation pane, expand...

   Resources | JMS | JMS providers

   

2. Set to cell scope, or to node or server scope for a V6 node.

3. In the content pane, click...

   WebSphere MQ messaging provider | Additional Properties | Connection factories | JMS_connection_factory_name

This type of connection factory is sometimes called a unified JMS connection factory, and supports the JMS 1.1 domain-independent interfaces, enabling applications to use the same, common, interfaces for both...

• point-to-point
• publish/subscribe messaging

A unified JMS connection factory also supports the domain-specific (queue and topic) interfaces, as used in JMS 1.0.2, so applications can still use those interfaces.

The property values specified must match the values specified when configuring WebSphere MQ for JMS resources.

In WebSphere MQ, names can have a maximum of 48 characters, with the exception of channels which have a maximum of 20 characters.

Name

The name by which this JMS connection factory is known for administrative purposes within IBM WAS. The name must be unique within the JMS connection factories across the WebSphere administrative domain.

JNDI name

Bind connection factories into the name space.

Use the fully qualified JNDI name...

jms/logicalName

The binding associates the resources defined by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the platform.

Description

For WAS administrative records.

Data type	String
Default	Null

Category

Classify or group this connection factory. For WAS administrative records.

Authentication mechanism preference

The authentication mechanism to be used for connections to WebSphere MQ created by this connection factory.

If WebSphere MQ is not configured to support the authentication mechanism preference, it is ignored.

Data type	Enum
Default	BASIC PASSWORD
Range	BASIC PASSWORD Authentication based on authentication alias ID/password, obtained from either... Component-managed authentication alias Container-managed authentication alias KerbV5 Authentication based on SSL certificates.

If you have enabled security for WAS, 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.

User IDs longer than 12 characters cannot be used for authentication with WebSphere MQ. For example, the default Windows user ID, Administrator, is not valid because it contains 13 characters. Therefore, an authentication alias for a WebSphere MQ queue connection factory must specify a user ID no longer than 12 characters.

To use Bindings transport mode on JMS queue connections to WebSphere MQ, you set the Transport type property to BINDINGS on the WebSphere MQ Queue Connection Factory. You must also choose one of the following options:

• To use security credentials, ensure that the user specified is the currently logged on user for the WAS process. If the user specified is not the current logged on user for the WAS process, then the WebSphere MQ JMS Bindings authentication throws the error MQJMS2013 invalid security authentication supplied for MQQueueManager.

• Do not specify security credentials. On the WebSphere MQ Connection Factory, ensure that both the Component-managed Authentication Alias and the Container-managed Authentication Alias properties are not set.

Manage cached handles

Whether or not cached handles (held in inst vars in a bean) should be tracked by the container.

Tracking handles can cause a large performance overhead if used at runtime; however, for debugging purposes it can be useful to enable handle management.

Data type	Check box
Default	Cleared
Range	Cleared Cached handles are not tracked by the container. Selected Cached handles are tracked by the container. You should select this option only for debugging purposes, because this can cause a large performance overhead.

Log missing transaction contexts

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

Data type	Check box
Default	Selected
Range	Selected When a connection is created, any missing transaction contexts are logged in the activity.log. Cleared Missing transaction contexts are not logged.

Queue manager

The name of the WebSphere MQ queue manager for this connection factory. Connections created by this factory connect to that queue manager.

Data type	String
Default	Null
Range	A valid WebSphere MQ queue manager name, as 1 through 48 ASCII characters

Host

The name of the host on which the WebSphere MQ queue manager runs, for client connection only.

Data type	String
Default	Null
Range	A valid TCP/IP hostname

Port

The TCP/IP port number used for connection to the WebSphere MQ queue manager, for client connection only.

This port must be configured on the WebSphere MQ queue manager.

Data type	Integer
Default	Null
Range	A valid TCP/IP port number, configured on the WebSphere MQ queue manager.

Channel

The name of the channel used for connection to the WebSphere MQ queue manager, for client connection only.

Data type	String
Default	Null
Range	1 through 20 ASCII characters

Transport type

Specify whether to use the WebSphere MQ client connection or JNI bindings for connection to the WebSphere MQ queue manager. WebSphere MQ as the JMS provider controls the communication protocols between JMS clients and JMS servers. Tune the transport type when you are using non-ASF nonpersistent, non-durable, non-transactional messaging or when you want to satisfy security issues and the client is local to the queue manager node.

Data type	Enum
Units	Not applicable
Default	BINDINGS
Range	BINDINGS JNI bindings are used to connect to the queue manager. BINDINGS is a shared memory protocol and can only be used when the queue manager is on the same node as the JMS client and comes at some security risks that should be addressed through the use of EJB roles. CLIENT WebSphere MQ client connection is used to connect to the queue manager. CLIENT is a typical TCP-based protocol.
Recommended	BINDINGS is faster by 30% or more, but it lacks security. When you have security concerns, CLIENT is more desirable than BINDINGS.

Model queue definition

The name of the model queue definition that can be used by the queue manager to create temporary queues if a queue requested does not already exist.

Data type	String
Default	Null
Range	1 through 48 ASCII characters

Client ID

The JMS client identifier used for connections to the WebSphere MQ queue manager.

Data type	String
Default	Null

CCSID

The coded character set identifier for use with the WebSphere MQ queue manager.

This coded character set identifier (CCSID) must be one of the CCSIDs supported by WebSphere MQ.

The term 'null' means leave blank; if you do this, a null value is passed and the default WebSphere MQ CCSID value is used.

Data type	String
Units	Integer
Default	Null
Range	1 through 65535

For more information about supported CCSIDs, and about converting between message data from one coded character set to another, see the WebSphere MQ System Administration and the WebSphere MQ Application Programming Reference books. These are available from the WebSphere MQ messaging multiplatform and platform-specific books Web pages; for example, at the IBM Publications Center, WebSphere MQ library, or from the WebSphere MQ collection kit, SK2T-0730.

Enable message retention

Whether or not unwanted messages are left on the queue. If this option is not enabled, unwanted messages are dealt with according to their disposition options.

Data type	Check box
Default	Cleared
Range	Selected Unwanted messages are left on the queue. Cleared Unwanted messages are dealt with according to their disposition options.

XA enabled

Specify whether the connection factory is for XA or non-XA coordination of messages and controls if the appserver uses XA QCF/TCF. Enable XA if multiple resources are not used in the same transaction.

If you clear this property, the JMS session is still enlisted in a transaction, but uses the resource manager local transaction calls (session.commit and session.rollback) instead of XA calls. This can lead to an improvement in performance. However, this means that only a single resource can be enlisted in a transaction in WAS.

Last participant support enables you to enlist one non-XA resource with other XA-capable resources.

Data type	Check box
Units	Not applicable
Default	Selected (XA enabled)
Range	Selected The connection factory is for XA-coordination of messages Cleared The connection factory is for non-XA coordination of messages
Recommended	Do not enable XA when the message queue received is the only resource in the transaction. Enable XA when other resources, including other queues or topics, are involved.

Enable return methods during shutdown

Whether or not applications return from a method call if the queue manager has entered a controlled shutdown.

Data type	Checkbox
Default	Selected
Range	Selected Applications return from a method call if the queue manager has entered a controlled shutdown. Cleared Applications do not return from a method call if the queue manager has entered a controlled shutdown.

Local server address

The range of local ports to be used when making a connection to a WebSphere MQ queue manager

If a JMS application attempts to connect to a WebSphere MQ queue manager in client mode, a firewall might allow only those connections that originate from specified ports or a range of ports. In this situation, you can use this property to specify a port, or a range of points, that the application can bind to.

Data type	String
Default	Null
Range	A string in the format: [ip-addr][(low-port[,high-port])] For example: 9.20.4.98 Channel binds to address 9.20.4.98 locally 9.20.4.98(1000) Channel binds to address 9.20.4.98 locally and uses port 1000 9.20.4.98(1000,2000) Channel binds to address 9.20.4.98 locally and uses a port in the range 1000 to 2000 (1000) Channel binds to port 1000 locally (1000,2000) Channel binds to a port in the range 1000 to 2000 locally You can specify a host name instead of an IP address. For direct connections, this property applies only when multicast is used and the value of the property must not contain a port number. If it does contain a port number, the connection is rejected. Therefore, the only valid values of the property are null, an IP address, or a host name.

Polling interval

The interval, in milliseconds, between scans of all receivers during asynchronous message delivery

Data type	Integer
Units	milliseconds
Default	5000
Range	1 through 2147483647

Rescan interval

The interval in milliseconds between which a topic is scanned to look for messages added to a topic out of order.

This interval controls the scanning for messages added to a topic out of order with respect to a WebSphere MQ browse cursor.

Data type	Integer
Units	milliseconds
Default	5000
Range	1 through 2147483647

SSL cipher suite

The cipher suite to use for SSL connection to WebSphere MQ.

Set this property to a valid cipher suite provided by your JSSE provider; it must match the CipherSpec named on the SVRCONN channel named by the Channel property.

Set this property if the SSL Peer Name property is to be set.

SSL CRL

A list of zero or more Certificate Revocation List (CRL) servers used to check for SSL certificate revocation. (Use of this property requires a WebSphere MQ JVM at Java 2 version 1.4.)

The value is a space-delimited list of entries of the form:

ldap://hostname:[port]

optionally followed by a single / (forward slash). If port is omitted, the default LDAP port of 389 is assumed. At connect-time, the SSL certificate presented by the server is checked against the specified CRL servers.

For more information about CRL security, see the section "Working with Certificate Revocation Lists" in the WebSphere MQ Security book; for example at: http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas012w.htm#IDX2254.

SSL peer name

For SSL, a distinguished name skeleton that must match the name provided by the WebSphere MQ queue manager. The distinguished name is used to check the identifying certificate presented by the server at connect-time.

The SSL Peer Name property is ignored if SSL cipher suite property is not specified.

List of attribute name and value pairs separated by commas or semicolons. For example:

CN=QMGR.*, OU=IBM, OU=WEBSPHERE

The example given checks the identifying certificate presented by the server at connect-time. For the connection to succeed, the certificate must have a Common Name beginning QMGR., and must have at least two Organizational Unit names, the first of which is IBM and the second WEBSPHERE. Checking is not case-sensitive.

For more details about distinguished names and their use with WebSphere MQ, see the WebSphere MQ Security book; for example, the section "Distinguished Names" at http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas010p.htm#HDRDCDN.

Temporary queue prefix

The prefix that is used for names of temporary JMS queues created by applications that use this connection factory.

Data type	String
Default	Null

Enable MQ connection pooling

Whether or not to use WebSphere MQ connection pooling.

Data type	Checkbox
Default	Selected
Range	Selected The connection factory enables and uses WebSphere MQ connection pooling. When a connection is no longer required, instead of destroying it, it can be pooled, and later reused. This can provide a substantial performance enhancement for repeated connections to the same queue manager. The WebSphere MQ connection pool is enabled the first time a connection is created from the connection factory. When the pool is enabled, it is used by all the WebSphere MQ connection factories defined on the appserver, regardless of the value of this property. When the last connection is removed from the WebSphere MQ connection pool, the pool is disabled. This behavior is due to the way the WebSphere MQ connection pool works.	Cleared The connection factory does not use WebSphere MQ connection pooling if the Websphere MQ connection pool is not active. When a connection is no longer required, it is destroyed. To use the same queue manager a new connection is created.

Broker control queue

The name of the publish/subscribe broker's control queue, to which publisher and subscriber applications send all command messages (except publications and requests to delete publications).

Data type	String
Default	Null
Range	1 through 48 ASCII characters

Broker queue manager

The name of the WebSphere MQ queue manager that provides the publish/subscribe message broker.

Data type	String
Default	Null
Range	1 through 48 ASCII characters

Broker publication queue

The name of the broker's input queue (stream queue) that receives all publication messages for the default stream. Applications can also send requests to delete publications on the default stream to this queue.

Data type	String
Units	En_US ASCII characters
Default	Null
Range	1 through 48 ASCII characters

Broker subscription queue

The name of the broker's queue from which non-durable subscription messages are retrieved. The subscriber specifies the name of the queue when it registers a subscription.

Data type	String
Default	Null
Range	1 through 48 ASCII characters

Broker CC subscription queue

The name of the broker's queue from which non-durable subscription messages are retrieved for a ConnectionConsumer. Applies only for use of the Web container.

Data type	String
Default	Null
Range	1 through 48 ASCII characters

Broker version

Whether the message broker is provided by the WebSphere MQ MA0C Supportpac or newer versions of WebSphere message broker products.

Data type	Enum
Default	Advanced
Range	Advanced The message broker is provided by newer versions of WebSphere message broker products, such as WebsSphere MQ Integrator and Event Broker. Basic The message broker is provided by the WebSphere MQ MA0C SupportPac (MQSeries - Publish/Subscribe) or MQSI working in MA0C compatibility mode.

Publish/subscribe cleanup level

The level of cleanup provided by the Publish/subscribe cleanup utility

To avoid the problems associated with non-graceful closure of subscriber objects, WebSphere MQ as a JMS provider provides a Publish/Subscribe cleanup utility that attempts to detect any earlier JMS publish/subscribe problems. If a large number of problems are detected, some performance degradation may be observed while resources are cleaned up. This utility runs transparently on a background thread and should not affect other WebSphere MQ operations.

Data type	Enum
Default	SAFE
Range	SAFE The Cleanup thread attempts to remove unconsumed subscription messages, or temporary queues, for failed subscriptions. This mode of cleanup does not interfere with the operation of other JMS applications. ASPROP The style of cleanup to use is determined by the system property com.ibm.mq.jms.cleanup, which is queried at JVM startup. Can be set on the java command-line using the -D option, and should be set to NONE, SAFE or STRONG. Any other value causes an exception. If not set, the property defaults to SAFE. This allows easy JVM-wide change to the Cleanup level without needing to update every topic connection factory used by the system. NONE In this special mode, no cleanup is performed; and no cleanup thread exists. Additionally, if the application is using the single-queue approach, unconsumed messages can be left on the queue. This option can be useful if the application is distant from the queue manager, and especially if it only publishes rather than subscribes. However, some application should perform cleanup on the queue manager to deal with any unconsumed messages - this could be a JMS application with CLEANUP(SAFE) or CLEANUP(STRONG), or the WebSphere MQ manual cleanup utility. STRONG The cleanup thread performs as CLEANUP(SAFE), but also clears the SYSTEM.JMS.REPORT.QUEUE of any unrecognized messages.

Publish/subscribe cleanup interval

The interval, in milliseconds, between background executions of the publish/subscribe cleanup utility.

Data type	Integer
Default	60000
Range	1 through 2147483647

Message selection

Whether message selection is done at the broker or client.

Data type	Enum
Default	BROKER
Range	BROKER Message selection is done at the broker. CLIENT Message selection is done at the client.

Publish acknowledgement interval

The interval, in number of messages, between publish requests that require acknowledgement from the broker.

Data type	Integer
Default	25
Range	1 through 2147483647

Enable sparse subscriptions

Select this option to support subscriptions that receive infrequent matching messages.

Data type	Checkbox
Default	Cleared
Range	Selected Subscriptions can receive infrequent matching messages. This value requires that the subscription queue can be opened for browse. Cleared Sparse subscriptions are not supported. Subscriptions receive frequent matching messages.

Publish/subscribe status interval

The interval, in milliseconds, between transactions to refresh publish/subscribe status.

Data type	Integer
Default	60000
Range	1 through 2147483647

Persistent subscriptions store

Where WebSphere MQ stores persistent data relating to active JMS subscriptions.

Data type	Enum
Default	MIGRATE
Range	MIGRATE This option dynamically selects the queue-based or broker-based subscription store based on the levels of queue manager and publish/subscribe broker installed. If both queue manager and broker are capable of supporting SUBSTORE(BROKER), this behaves as SUBSTORE(BROKER); otherwise it behaves as SUBSTORE(QUEUE). Additionally, SUBSTORE(MIGRATE) transfers durable subscription information from the queue-based subscription store to the broker-based store. QUEUE Subscription information is stored on SYSTEM.JMS.ADMIN.QUEUE and SYSTEM.JMS.PS.STATUS.QUEUE on the local queue manager. BROKER Subscription information is stored by the publish/subscribe broker used by the application. This option requires recent levels of queue manager and publish/subscribe broker. This subscription store requires recent levels of both queue manager and publish/subscribe broker. It is designed to provide improved resilience.

Enable multicast transport

Whether or not this connection factory uses multicast transport.

With multicast, messages are delivered to all consumers. This is useful in environments where there are a large number of clients that all want to receive the same messages, because with multicast only one copy of each message is sent. Multicast reduces the total amount of network traffic. Reliable multicast is standard multicast with a reliability layer added.

Data type	Enum
Default	NOTUSED
Range	NOTUSED This connection factory does not use multicast transport. ENABLED This connection factory uses multicast transport, but does not provide a reliable multicast connection. ENABLED_IF_AVAILABLE This connection factory uses multicast transport if the message broker supports it. ENABLED_RELIABLE This connection factory uses reliable multicast transport ENABLED_RELIABLE_IF_AVAILABLE This connection factory uses reliable multicast transport if the message broker supports it.

Enable clone support

Select this check box to enable clone support to allow the same durable subscription across topic clones.

Data type	check box
Default	Cleared
Range	Selected Clone support is enabled. Cleared Clone support is disabled.

If you select this property, also specify a value for the Client ID property.

Direct broker authentication

Whether the broker uses basic or certificate-based authentication for direct connections.

Authentication on a direct connections (if the TRANSPORT property is set to DIRECT).

Data type	Enum
Default	NONE
Range	NONE Direct broker authentication is not used. PASSWORD Password-based authentication is used for direct connections. Authentication is performed based on a user ID and password provided by an authentication alias. The authentication alias used is obtained from one of the following properties: Component-managed Authentication Alias Container-managed Authentication Alias CERTIFICATE Certificate-based authentication is used for direct connections. The SSLPEERNAME and SSLCRL properties are used to perform the authentication checks. You can use certificate-based authentication when connecting directly to a WebSphere Business Integration Event Broker or WebSphere Business Integration Message Broker broker.

Proxy host name

Host name of the Web Scale proxy host.

A direct connection is made to the proxy server, which forwards the connection request to the message broker. If the TRANSPORT property is set to DIRECT, the type of connection to the message broker depends on the value of this property, according to the following rules:

• If this property is set to the empty string, a direct connection is made to the broker identified by the HOSTNAME and PORT.

• If this property is set to a value other than the empty string, a direct connection is made to the broker through the proxy server identified by this property and the PROXYPORT property.

Data type	String
Default	Null

Proxy port

Port number of the Web Scale proxy port.

A direct connection is made to this port on the proxy server identified by the PROXYHOSTNAME property, which forwards the connection request to the message broker.

Data type	Integer
Default	0

Connection pool

Optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The appserver pools connections and sessions with the JMS provider to improve performance. This is independent from any WebSphere MQ connection pooling. We need to configure the connection and session pool properties appropriately for your applications, otherwise you may not get the connection and session behavior that you want.

Change the size of the connection pool if concurrent server-side access to the JMS resource exceeds the default value. The size of the connection pool is set on a per queue or topic basis.

Session pools

An optional set of session pool settings.

This link provides a panel of optional connection pool properties, common to all J2C connectors.

The appserver pools connections and sessions with the JMS provider to improve performance. This is independent from any WebSphere MQ connection pooling. We need to configure the connection and session pool properties appropriately for your applications, otherwise you may not get the connection and session behavior that you want.

Custom properties

An optional set of name and value pairs for custom properties passed to WebSphere MQ.

 

Configuration tab

Scope

Level to which this resource definition is visible to applications.

Resources such as messaging providers, namespace bindings, or shared libraries can be defined at multiple scopes, with resources defined at more specific scopes overriding duplicates which are defined at more general scopes.

The scope displayed is for information only, and cannot be changed on this panel. 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.

Mapping-configuration alias

The module used to map authentication aliases.

List of the modules configured on...

Security | JAAS Configuration | Application Logins Configuration

Data type	Enum
Default	Null
Range	ClientContainer The client container maps authentication aliases. WSLogin The WSLogin module maps authentication aliases. DefaultPrincipalMapping The JAAS configuration maps an authentication alias to its userid and password.

---

 

Related tasks

Manage JCA authentication data entries
Asynchronous messaging - security considerations
Configure a unified JMS connection factory, for WebSphere MQ
WebSphere MQ queue connection factory settings
WebSphere MQ library
JMS interfaces - explicit polling for messages
SSL properties in WebSphere MQ