WebSphere MQ topic connection factory settings

 

+

Search Tips   |   Advanced Search

 

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

A WebSphere MQ topic connection factory is used to create JMS connections to topic destinations provided by WebSphere MQ for publish/subscribe messaging.

To view this page, use the administrative 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 administrative console presents the subset of resources and properties that are applicable to WebSphere Application Server V5.

  3. In the content pane, under Additional Resources, click WebSphere MQ Topic Connection Factories. This displays a list of any existing JMS topic connection factories.

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

A WebSphere MQ topic connection factory has the following properties.

Note:

Name

The name by which this topic connection factory is known for administrative purposes within IBM WebSphere Application Server.

Data type String

JNDI name

The JNDI name that is used to bind the topic 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 topic connection factory for administrative purposes within IBM WebSphere Application Server.

Data type String
Default Null

Category

A category used to classify or group this topic 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 that have been defined to WebSphere Application Server. We 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.

 

Restriction

  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. If you want 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 that have been defined to WebSphere Application Server. We 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.

 

Restriction

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

Transport type

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

DIRECT

For a WebSphere MQ message broker using DIRECT mode. DIRECT is a lightweight sockets protocol used in non-transactional, non-durable and non-persistent Publish/Subscribe messaging. DIRECT works only for clients and message-driven beans using the non-ASF protocol.

The type of connection to the message broker depends on the value of the PROXYHOSTNAME property, according to the following rules:

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

  • If the PROXYHOSTNAME 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.

Recommended DIRECT is the fastest transport type and should be used where possible. Use BINDINGS when you want to satisfy additional security tasks and the queue manager is local to the JMS client. QUEUED is fallback for all other cases.

Note: WebSphere MQ 5.3 before CSD2 with the DIRECT setting can lose messages when used with message-driven beans and under load. This also happens with client-side based applications unless the broker's maxClientQueueSize is set to 0. We can set this to 0 with the command #wempschangeproperties WAS_nodeName_server1 -e default -o DynamicSubscriptionEngine -n maxClientQueueSize -v 0 -x executionGroupUUID, where executionGroupUUID can be found by starting the broker and looking in the Event Log/Applications for event 2201. This value is usually ffffffff-0000-0000-000000000000.

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

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. This property 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 WebSphere Business Integration Message Broker 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.

Model queue definition

The name of the model queue definition that the broker can use to create dynamic queues for non-default streams if the stream queue does not already exist

The name of the model queue definition that the broker can use to create dynamic queues to receive publications for streams other than the default stream. This is only used if the stream queue does not already exist. If this model queue definition does not exist, all stream queues must be defined by the administrator.

Data type String
Default Null
Range 1 through 48 ASCII characters

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.

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.

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 http://www-3.ibm.com/software/ts/mqseries/library/manualsa/manuals/platspecific.html, the IBM Publications Center, or from the WebSphere MQ collection kit, SK2T-0730.

XA Enabled

Specifies whether the connection factory is for XA or non-XA coordination of messages and controls if the application server uses XA. Enable XA if multiple resources are not 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 WebSphere Application Server.

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.

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. This property 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.

Direct broker authentication

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

This property selects the 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:

CERTIFICATE

Certificate-based authentication is used for direct connections. The SSLPEERNAME and SSLCRL properties are used to perform the authentication checks.

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. For more information, see the description of the PROXYHOSTNAME property.

Data type Integer
Default 0

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, 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

We 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 that have been added to a topic out of order.

This interval controls the scanning for messages that have been 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 href="#MQQueueConnectionFactory_channel">Channel property.

You must set this property if the href="#SSLPEERNAME"> 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; for example, the section "Distinguished Names" at http://publibfp.boulder.ibm.com/epubs/html/csqzas01/csqzas010p.htm#HDRDCDN.

Enable MQ 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

Specifies an optional set of connection pool settings.

Connection pool properties are common to all J2C connectors.

The application server pools connections and sessions with the JMS provider to improve performance. This is independent from any WebSphere MQ connection pooling. 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 application server pools connections and sessions with the JMS provider to improve performance. This is independent from any WebSphere MQ connection pooling. 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

Specifies the 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. 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.

Data type String

Mapping-configuration alias

The module used to map authentication aliases.

This field provides a list of the modules that have been configured on the Security > JAAS Configuration > Application Logins Configuration property. For more information about the mapping configurations, see href="Configuration_entry_settings_for_JAAS.html">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

 


 

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.