WebSphere caching connection factory

Creates cached (non-XA) JMS connections to WebSphere MQ servers.

To use this connection factory, copy the following Java libraries from your WebSphere MQ installation location to the extensions directory of the eMagiz runtime:

  • com.ibm.mq.jmqi.jar
  • com.ibm.mqjms.jar
  • dhbcore.jar

Tested with version 7.1 of WebSphere MQ; should also work with all versions that have a compatible ConnectionFactory interface.

Id

Name that uniquely identifies this flow component.

Required

Username

Optional username that is used for creating connections to the JMS server.

If not set (the default), the handling of user identities when creating connections is controlled by the system property com.ibm.mq.jms.ForceUserID which takes one of two values:

  • false: If an application passes an empty string for the User ID when creating a connection, the empty string is sent to the queue manager for authentication.
  • true: If the application passes an empty string for the User ID when creating a connection, then the User ID that started the JVM will be sent to the queue manager for authentication.

To set this property, applications using the WebSphere MQ classes for JMS need to be started with the following JVM argument: -Dcom.ibm.mq.jms.ForceUserID=true or -Dcom.ibm.mq.jms.ForceUserID=false

Password

Optional password that is used for creating connections to the JMS server.

Must be provided if and only if the username property is also set.

Session cache size

Specify the desired size for the JMS session cache (per JMS session type).

This cache size is the maximum limit for the number of cached sessions per session acknowledgement type (auto, client, dups_ok, transacted). As a consequence, the actual number of cached sessions may be up to four times as high as the specified value - in the unlikely case of mixing and matching different acknowledgement types.

Default is 1: caching a single session, (re-)creating further ones on demand. Specify a number like 10 if you'd like to raise the number of cached sessions; that said, 1 may be sufficient for low-concurrency scenarios.

Cache producers

Whether to cache JMS message producers per JMS session instance (more specifically: one message producer per destination and session), or not cache message producers at all.

Default is true. Switch this to false in order to always recreate message producers on demand.

Cache consumers

Whether to cache JMS message consumers per JMS session instance (more specifically: one message consumer per destination, selector string and session), or not cache message consumers at all.

Note that durable subscribers will only be cached until logical closing of the session handle.

Default is true. Switch this to false in order to always recreate message consumers on demand.

Important performance consideration When this connection factory is used by a JMS outbound gateway with an explicit reply destination configured, the gateway uses a message selector that expects a JMSCorrelationID to match the outbound request's JMSMessageID. If this property is set to true, that can lead to an OutOfMemoryException since each consumer's cache key is unique (basically the destination + the message selector). Obviously, that also means we are not benefiting from the potential performance benefits of caching message consumer instances either (rather than creating with each request/reply operation). So in these cases, either set this property to false, or use a reply listener on the gateway.

Client ID

Specify a JMS client ID for the single connection created and exposed by this connection factory.

Note that client IDs need to be unique among all active connections of the underlying JMS provider. Furthermore, a client ID can only be assigned if the original connection factory hasn't already assigned one.

Optional

Reconnect on exception

Specify whether the single connection should be reset (to be subsequently renewed) when a JMS exception is reported by the underlying connection.

Default is true, which will automatically trigger recovery based on your JMS provider's exception notifications.

Internally, this will lead to a special JMS exception listener (this connection factory itself) being registered with the underlying connection. This can also be combined with a user-specified exception listener, if desired.

Reconnect on failover

Whether connection failure exceptions that are successfully failed over (recognizable by error code FAILOVER) should cause the connection to reconnect.

In case of HornetQ, the exception listener is always called on event of connection failure, irrespective of whether the connection was successfully failed over, reconnected or reattached. The error code FAILOVER in such cases indicates that failover was successful, and that we still have a working connection.

Default is false.

Host name

The name of the host.

Port

The port for a client connection.

Queue manager

The queue manager which is used when selecting a channel definition. This can be in one of the following forms:

  • "qMgrName", where the actual name of the required queue manager is passed in. The channel must connect to a queue manager of this name.
  • "qMgrName", where "" followed by the actual name of the required queue manager is passed in. The channel definition that is used must specify this queue manager name. This full name is passed onto the queueManager during a connect, but the queue manager that is ultimately connected to may not have the same name as specified here after the "*".
  • "*" or "" or a name which consists entirely of blanks is used. The actual queue manager name is disregarded when a channel definition is being selected.

Transport type

Permitted values are: 0: WMQ_CM_BINDINGS 1: WMQ_CM_CLIENT 2: WMQ_CM_DIRECT_TCPIP 4: WMQ_CM_DIRECT_HTTP

Channel

The name of the channel; applies to client transport mode only.

Description

The description for this connection.

Local address

The local address to be used. The format of a local address is [ip-addr][(low-port[,high-port])].

Some examples:

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

Proxy host name

The host name of the proxy server when establishing a real-time connection.

Proxy port

The port number of the proxy server when establishing a real-time connection.

Client ID

The client ID.

SSL cipher suite

The CipherSuite used for SSL encryption. Set this to the CipherSuite matching the CipherSpec set on the SVRCONN channel.

Default is empty, which indicates no SSL encryption is performed.

SSL FIPS required

Whether SSLFips (FIPS) is required.

SSL peer name

A distinguished name (DN) pattern. If SSL cipher suite is set, this pattern can ensure that the correct queue manager is used. The connection attempt fails if the distinguished name provided by the queue manager does not match this pattern.

This property is ignored if SSL cipher suite is empty.

Default is empty, which indicates no checking of the queue manager's DN pattern is performed.

SSL reset count

The SSL reset count. This must be an integer with a value between 0 (disabled) and 999 999 999.

Async exceptions

The exception types that should be passed to the user's exception listener.

Permitted values are: -1: ASYNC_EXCEPTIONS_ALL (default) 1: ASYNC_EXCEPTIONS_CONNECTIONBROKEN

Client reconnect options

Specifies the client reconnect options for new connections created by this factory.

Permitted values are:

0: WMQ_CLIENT_RECONNECT_AS_DEF (default) Use the value specified in the mqclient.ini file. This is set using the DefRecon property within the Channels stanza. It can be set to one of:

  • YES: behaves as the WMQ_CLIENT_RECONNECT option
  • NO (default): does not specify any reconnection options
  • QMGR: behaves as the WMQ_CLIENT_RECONNECT_Q_MGR option
  • DISABLED: behaves as the WMQ_CLIENT_RECONNECT_DISABLED option

16777216: WMQ_CLIENT_RECONNECT Reconnect to the any of the queue managers specified in the connection name list.

67108864: WMQ_CLIENT_RECONNECT_Q_MGR Reconnect to the same queue manager we were originally connected to. This will throw MQRC_RECONNECT_QMID_MISMATCH if the queue manager it tries to connect to (specified in the connection name list) has a different QMID to the queue manager originally connected to.

33554432: WMQ_CLIENT_RECONNECT_DISABLED Reconnection is disabled.

Connection name list

Specifies the hosts to which the client will attempt to reconnect to after its connection is broken. The connection name list is a comma seperated list of host/ip port pairs, for example: 127.0.0.1(1414),host2.example.com(1400).

Default is localhost(1414).

Client reconnect timeout

The amount of time (in seconds) that a client connection will attempt to reconnect. After attempting to reconnect for this amount of time, the client will fail with MQRC_RECONNECT_FAILED.

Default is 1800 (30 minutes).

Cleanup interval

The clean up interval (in milliseconds).

Cleanup level

The clean up level.

Permitted levels are: -1: WMQ_CLEANUP_AS_PROPERTY 0: WMQ_CLEANUP_NONE 1: WMQ_CLEANUP_SAFE (default) 2: WMQ_CLEANUP_STRONG 4: WMQ_CLEANUP_NONDUR 3: WMQ_CLEANUP_FORCE

Direct auth

The type of direct authentication that is required.

Permitted values are: 0: RTT_DIRECT_AUTH_BASIC 1: RTT_DIRECT_AUTH_CERTIFICATE

Fail if quiesce

The default behavior of applications accessing a quiescing queue manager.

Permitted values are: 1: WMQ_FIQ_YES (default) 0: WMQ_FIQ_NO

Max buffer size

The maximum buffer size. This is the maximum number of received messages that can be stored in an internal message buffer while waiting to be processed by the client application. This property applies only when using the DIRECT or DIRECTHTTP transport type.

Message retention

What happens to unwanted messages.

Permitted values are: 1: WMQ_MRET_YES (default) 0: WMQ_MRET_NO

Message selection

Whether the client or the broker performs message selection.

Permitted values are: 0: WMQ_MSEL_CLIENT (default) 1: WMQ_MSEL_BROKER

Message batch size

The maximum number of messages to be taken at once when using asynchronous delivery.

Multicast

Permitted values are: 0: RTT_MULTICAST_DISABLED (default) 3: RTT_MULTICAST_NOT_RELIABLE 5: RTT_MULTICAST_RELIABLE 7: RTT_MULTICAST_ENABLED

Polling interval

The interval (in milliseconds) between scans of all receivers during asynchronous message delivery.

Pub ack interval

The number of messages that can be published before requiring acknowledgement from the broker. Applications do not normally alter this value, and must not rely on this acknowledgement.

Default is 25.

Rescan interval

The interval (in milliseconds) between browsing a queue. The scan looks for messages that were not returned by the previous scan.

Send check count

The interval between send calls to check for asynchronous put errors, measured as a count of message sends within a single non-transacted JMS session.

Share conv allowed

Whether client connections can share their socket (conversation).

Permitted values are: 0: connections are not allowed to share their socket 1: the connection is allowed to share the socket with other top-level JMS connections from the same process to the same queuemanager, provided that the channel definitions match

Status refresh interval

The time (in milliseconds) between transactions to refresh publish/subscribe status.

Subscription store

Permitted values are: 0: WMQ_SUBSTORE_QUEUE 1: WMQ_SUBSTORE_BROKER 2: WMQ_SUBSTORE_MIGRATE (default)

Syncpoint all GETs

Whether to do all GET operations within a syncpoint.

Default is false.

Target client matching

Enables or disables target client matching. If this is set to true, then only MQMD messages (those from a non-JMS application) containing a replyTo will have a JMS replyTo ProviderDestination constructed with targetClient set to 1 (WMQ_CLIENT_NONJMS_MQ). This ensures that the reply can be understood by the originator.

If this field is set to false, then replies will always contain an RFH2 header, even though the receiver might not understand the reply.

Note that this applies only to point-to-point destinations.

Default is true.

Temporary model

The name of the WebSphere MQ model queue. If refers to a model queue that can be used to create a permanent dynamic queue then you must call the MQTemporaryQueue.delete() method to destroy the queue after use.

Within the WebSphere Application Server, MQTemporaryQueue.delete() will be called by the application server when a connection is being closed. Therefore even if a permanent dynamic model queue is used, the created temporary queue will be destroyed.

Temp topic prefix

The prefix to use when creating temporary topic names.

When creating temporary topics, JMS will generate a topic string of the form TEMP/<prefix>/<unique id>, or if this property is left with the default value, just TEMP/<unique id>.

Temp Q prefix

The prefix to be used to form the name of a WebSphere MQ dynamic queue. This must end with the '*' character.

← XSLT transformerSFTP composite file list filter →