WebSphere MQ queue connection factory settings

 

+

Search Tips   |   Advanced Search

 

Use this panel to view or change the configuration properties of the selected queue connection factory for use with the WebSphere MQ JMS provider. These configuration properties control how connections are created to the associated JMS queue destination.

A WebSphere MQ queue connection factory is used to create JMS connections to queues provided by WebSphere MQ for point-to-point messaging. To view this page, use the console to complete the following steps:

  1. In the navigation pane, expand...

    Resources | JMS Providers | WebSphere MQ

  2. If appropriate, in the content pane, change the scope of the WebSphere MQ messaging provider. If the scope is set to node or server scope for a Version 5 node, the console presents the subset of resources and properties that are applicable to WAS V5.

  3. In the content pane, under Additional Resources, click...

    WebSphere MQ Queue Connection Factories

    This displays a list of any existing JMS queue connection factories.

  4. Click the name of the JMS connection factory to work with.

A queue connection factory for the WebSphere MQ JMS provider has the following properties.

Name

The name by which this queue connection factory is known for administrative purposes within IBM WAS.

Data type String

JNDI name

The JNDI name that is used to bind the connection factory into the name space.

As a convention, use the fully qualified JNDI name; for example, in the form jms/Name, where Name is the logical name of the resource.

This name is used to link the platform binding information. The binding associates the resources defined by the deployment descriptor of the module to the actual (physical) resources bound into JNDI by the platform.

Data type String

Description

A description of this connection factory for administrative purposes within IBM WAS.

Data type String
Default Null

Category

A category used to classify or group this connection factory, for your IBM WAS administrative records.

Data type String

Component-managed authentication alias

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

This property provides a list of the J2C authentication data entry aliases defined to WAS. 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 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.

  1. 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.

  2. 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.

Container-managed authentication alias

This alias specifies a user ID and password to be used to authenticate connection to a JMS provider for container-managed authentication.

This property provides a list of the J2C authentication data entry aliases defined to WAS. 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 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.

  1. 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.

  2. 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.

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 0
Range A valid TCP/IP port number, configured on the WebSphere MQ queue manager.

Transport type

Whether the WebSphere MQ client connection or JNI bindings are used for connection to the WebSphere MQ queue manager.

WebSphere MQ, as the messaging provider, controls the communication protocols between JMS clients and JMS servers. Tune the transport type when you are using non-ASF non-persistent, 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 that can be used only 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-mode offers best performance but the SYSTEM.DEF.SVRCONN must be disabled by specifying an invalid MCAUSER user ID. No other configuration is required.

Client mode uses SSL-encrypted MQI channels and certificate-based authentication using SSLPEER, and the queue manager can be located on a remote server. SSL configuration (such as certificate management) is required between WAS and WebSphere MQ, and J2C authentication aliases are also required.

Unless WebSphere MQ cannot be installed on the same machine as the appserver, bindings mode is the logical choice. However, client mode is enabled by default so it is still necessary to disable the SYSTEM.DEF.SVRCONN channel to prevent unauthorized client access. If the MCAUSER attribute of the SYSTEM.DEF.SVRCONN channel specifies an invalid user ID, authorization is denied for all client mode access. For additional information, see: 

http://www-128.ibm.com/developerworks/ibm/library/i-supply1i/

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

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

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 WebSphere MQ.

Data type String
Range A valid JMS client ID, as ASCII characters

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 library at http://www-306.ibm.com/software/integration/wmq/library/, the IBM Publications Center, 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 Enum
Default Selected
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. Enable XA if multiple resources are used in the same transaction.

If you clear this property (non-XA), 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 Checkbox
Default Selected
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 select to enable XA when the message queue received is the only resource in the transaction. Enable XA if transactions involve other resources, including other queues or topics.

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 local server address

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

    The channel binds to address 9.20.4.98 locally

  • 9.20.4.98(1000)

    The channel binds to address 9.20.4.98 locally and uses port 1000

  • 9.20.4.98(1000,2000)

    The channel binds to address 9.20.4.98 locally and uses a port in the range 1000 to 2000

  • (1000)

    The channel binds to port 1000 locally

  • (1000,2000)

    The 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 queue is scanned to look for messages added to a queue out of order.

This interval controls the scanning for messages added to a queue out of order with respect to a WebSphere 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. This property is a 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 at http://www-306.ibm.com/software/integration/wmq/library/.

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

Use connection pooling

Whether or not to use WebSphere MQ connection pooling.

Data type Checkbox
Default Selected
Range

Selected

The connection factory 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.

Cleared

The connection factory does not use WebSphere MQ connection pooling. When a connection is no longer required, it is destroyed. To use the same queue manager a new connection is created.

Connection pool

An 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 pool

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.

 

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.

Data type String

Mapping-configuration alias

The module used to map authentication aliases.

This field provides a list of the modules configured on the Security > JAAS Configuration > Application Logins Configuration property. For more information about the mapping configurations, see Java Authentication and Authorization service configuration entry settings.

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 J2EE Connector Architecture authentication data entries
Asynchronous messaging - security considerations
Configure a unified JMS connection factory, for WebSphere MQ
Configure a JMS queue connection factory for WebSphere MQ

 

Related Reference

WebSphere MQ queue connection factory settings WebSphere MQ library Web page at http://www-3.ibm.com/software/ts/mqseries/library

 

Related information


JMS interfaces - explicit polling for messages

 

Reference topic