WebSphere WebSphere Application Server Network Deployment, Version 6.0.x Operating Systems: AIX, HP-UX, Linux, Solaris, Windows

Common JMS-related entities for reuse (conrefs)

This file lists common JMS-related entities for reuse in other DITA topics (through conrefs)

Configuration [Scope settings]

Specifies the level to which this resource is visible: the cell, node, or server level.

Use scope settings to limit the availability of resources to a particular cell, node, or server. When new resources are created in this view, they are created within the selected scope.

Resources such as JMS providers can be defined at multiple scopes, with resources defined at more specific scopes overriding duplicates that are defined at more general scopes.

Note: The resource's properties only apply at an individual server level, regardless of the scope of a defined resource. For example, if you define the scope of a data source at the Cell level, all users in that Cell can look up and use that data source, which is unique within that Cell. However, resource property settings are local to each server in the Cell. For example, if you set Max Connections to 10, then each server in that Cell can have 10 connections.

The value you set for this check box is displayed in the Scope field on this panel.

Data type Enum
Default Node
Range
Cell
The most general scope. Resources defined at the Cell scope are visible from all nodes and servers, unless they are overridden. To view resources defined in a cell scope, select a cell name in the scope selection form.
Node
Resources defined at the Node scope override any duplicates defined at the Cell scope and are visible to all servers on the same node, unless they are overridden at a server scope on that node. To view resources defined in a node scope, select a node name in the scope selection form.
Server
The most specific scope for defining resources. Resources defined at the Server scope override any duplicate resource definitions defined at the Cell scope or parent Node scope and are visible only to a specific server. To view resources defined in a server scope, select a server name in the scope selection form.

Scope

Specifies the level to which this resource is visible: the cell, node, or server level.

This field displays the value that you set on the Configuration scope selection form on this panel.

Data type Enum
Default Node
Range Cell, Node, or Server.

Name

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

Data type String

JNDI name

The JNDI name that is used to bind the connection factory into the application server's 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..

Data type String
Default Null

Node

The WebSphere node name of the administrative node where the JMS server runs for this connection factory. Connections created by this factory connect to that JMS server.

Data type String
Units Enum
Default Null
Range Pull-down list of nodes in the WebSphere administrative domain.

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

Note: User IDs longer than 12 characters cannot be used for authentication with the Version 5 default messaging provider. For example, the default Windows NT user ID, Administrator, is not valid for use with the Version 5 default messaging provider, because it contains 13 characters. Therefore, an authentication alias for a Version 5 WebSphere connection factory must specify a user ID no longer than 12 characters.

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

Note: User IDs longer than 12 characters cannot be used for authentication with the Version 5 default messaging provider. For example, the default Windows NT user ID, Administrator, is not valid for use with the Version 5 default messaging provider, because it contains 13 characters. Therefore, an authentication alias for a Version 5 WebSphere connection factory must specify a user ID no longer than 12 characters.

Queue manager

The name of the 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

Port

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

This port must be configured on the queue manager.

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

Channel

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

Data type String
Default Null
Range 1 through 20 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

Message retention

Select this tick box to specify that unwanted messages are to be left on the queue. Otherwise, unwanted messages are dealt with according to their disposition options.

Data type Enum
Units Not applicable
Default Cleared
Range
Selected
Unwanted messages are left on the queue.
Cleared
Unwanted messages are dealt with according to their disposition options.

XA Enabled

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

If you set this property to 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. In WebSphere Application Server Enterprise the last participant support enables you to enlist one non-XA resource with other XA-capable resources.

For a WebSphere Topic Connection Factory with the Port property set to DIRECT this property does not apply, and always takes the value NON_XA.

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

Host

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

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

Port

Which of the two ports that connections use to connect to the JMS Server. The QUEUED port is for full-function JMS publish/subscribe support, the DIRECT port is for non-persistent, non-transactional, non-durable subscriptions only.

Note: Message-driven beans cannot use the direct listener port for publish/subscribe support. Therefore, any topic connection factory configured with Port set to Direct cannot be used with message-driven beans.
Data type Enum
Units Not applicable
Default QUEUED
Range
QUEUED
The listener port used for full-function JMS-compliant, publish/subscribe support.
DIRECT
The listener port used for direct TCP/IP connection (non-transactional, non-persistent, and non-durable subscriptions only) for publish/subscribe support.

The TCP/IP port numbers for these ports are defined on the JMS Server.

Transport type

Specifies whether the WebSphere MQ client connection or JNI bindings are used for connection to the WebSphere MQ queue manager. The external JMS provider controls the communication protocols between JMS clients and JMS servers. Tune the transport type when you are using non-ASF nonpersistent, nondurable, nontransactional 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 WebSphere MQ Event Broker using DIRECT mode. DIRECT is a lightweight sockets protocol used in nontransactional, nondurable and nonpersistent Publish/Subscribe messasging. DIRECT is only works for clients and message-driven beans using the non-ASF protocol.
QUEUED
QUEUED is a standard TCP protocol.
Recommended
Queue connection factory transport type
BINDINGS is faster by 30% or more, but it lacks security. When you have security concerns, BINDINGS is more desirable than CLIENT.
Topic connection factory transport type
DIRECT is the fastest 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. You 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.

Client ID

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

This client ID is used if the application does not use the Connection.setClientID(String) method to specify a client ID.

Data type String
Default Null

Clone Support

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

Data type Enum
Units Not applicable
Default Cleared
Range
Selected
Clone support is enabled.
Cleared
Clone support is disabled.

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

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
Units En_US ASCII characters
Default Null
Range 1 through 48 ASCII characters

Cell name

The name of the cell to which applications should be connected.

This does not have to be the same as the cell in which the application is deployed.

For thin clients this field must be specified. For other usage, this field is optional and, if left to default, the name of the home cell is used.

Data type String
Default home cell name

Bus name

The name of the message bus to which applications should be connected.

This name is qualified by the cell name.

Data type String
Default Null

Channel Chain Name

The name of a pre-configured channel chain used to communicate with the messaging engine.

Data type String
Default Null

Target name

The name used to identify the WLM target group that refines where applications should be connected.

This indicates the name of one of the following types of targets:
  • A messaging engine. Retrieves the available endpoints that can be used to reach the named messaging engine.
  • A destination. Retrieves the active messaging engines that localize the named destination.
  • An application server. Retrieves the active messaging engine that is hosted by the named server.
  • An application server cluster. Retrieves the active messaging engines that are hosted by members of the named server cluster.
  • A user-specified group of messaging engines (that form a self-declaring cluster). Retrieves the active messaging engines that have registered with the named user-specified group.

This name is qualified by the cell name and, if needed, bus name. For an application server or server cluster, the cell name is enough, because their WLM target group namespace is at the cell level. For messaging engine, messaging engine group, and destination, the name is qualified by both the cell and bus names.

Connections are load balanced across the available messaging engines that satisfy the selection criteria:
  • If the Target name value is not specified, applications are connected to any available messaging engine on the identified bus.
  • If the Target name value is specified, it refines where applications are connected to on the identified bus (see Bus name).

    For example, if Target name specifies the name of a destination and Target significance is set to Preferred, then the createConnection() method tries to connect to a messaging engine that localizes the named destination. If the connection cannot be completed (for example, because no such messaging engines are running), then an attempt is made to connect to some other messaging engine that is available on the same bus.

    To make a specific connection, set Target significance to Critical. This forces the createConnection() method to try to connect to the target identified by the Target name property; for example, a specific messaging engine or application server, or the name of a destination with only one localization. In this critical case, if there is no available messaging engine that hosts the target, then the connection fails.

Data type String
Default Null

If the Target name value is not specified, applications are connected to any available messaging engine on the identified bus.

Target significance

Whether the WLM target group name is critical or only helpful to lookup the target.

Data type Enum
Default Preferred
Value
Preferred
The target name is a help to lookup the target. If the target name cannot be resolved, it is ignored and the connection continues.
Critical
The target name is critical to lookup the target. If the target name cannot be resolved, then the connection fails.

Durable Subscription Home

The name of the messaging engine where all durable subscriptions accessed through this connection are managed.

This property must be set if durable subscriptions are to be created using connections created from this connection factory.

Data type Enum
Default Null
Range A list of messaging engines available.

Non persistent QOS

The acceptable reliability for message delivery, as a quality of service, for non-persistent JMS messages.

This property can also be set on the JMS destination, in which case the JMS destination setting overrides this value.

Data type Integer
Default Express
Range
Express
Messages are delivered on a "best-effort" basis, and it is acceptable if some are lost or discarded by the system; for example, due to a messaging engine failing or lacking resources.
Reliable
Messages can be lost if a messaging engine fails, but are not lost under normal operating conditions. The messaging engine does not discard messages due to lack of resources, but exerts back pressure on producers or spills messages to disk to relieve resource constraints.

SSL Ciphersuite

Indicates that the client/server protocol must be protected by SSL (in the case of HTTP tunnelling this means that the protocol will be HTTPS), and specifies the SSL cipherSuite to be used.

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.

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

SSL Peer Name

For SSL, an X.509 distinguished name skeleton that must match the name provided by the bus. The distinguished name is used to check the identifying certificate presented by the server at connect-time.

If SSL Peer Name and SSL Ciphersuite are set, then a certificate is requested from the server, and the server's distinguished name is checked against the value provided here

SSL Peer Name is ignored if SSL Ciphersuite is not specified.

The SSL Peer Name 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.

Proxy

For an HTTP transport, this defines the URL of an HTTP proxy server.

If the Transport property is set to HTTP this field can be set to the URL of an HTTP proxy server. If Transport is not set to HTTP, then this field is ignored

Data type URL
Default Null
Range A valid HTTP URL value.

Model Destination Name

The name of the model destination that the connection factory can use to create temporary destinations.

Data type String
Range
If you leave this property to default, the default model destination for the type of destination is used. The type-specific default model destinations are named as follows:
  • SYSTEM.DEFAULT.MODEL.QUEUE, the default model queue destination for point-to-point messaging.
  • SYSTEM.DEFAULT.MODEL.TOPICSPACE, the default model topic destination for publish/subscribe messaging.

Model Destination Prefix

A prefix that is used when generating temporary destinations from this connection factory, so that the temporary destinations can be easily associated with the application that created them.

Data type String
Range

Name Space

The default namespace within which JMS destinations are referenced if the associated destination does not specify a namespace.

Data type String
Range

Name Space

The default namespace within which this JMS destination is referenced.

If you do not specify a value for this property, the destination is referenced within the namespace specified for the connection factory.

Data type String
Range

Destination

The destination on the service integration bus that provides this JMS destination.

Data type Enum
Range

Topic name

The topic on the service integration bus that provides this JMS topic destination.

Data type Enum
Range A name of an SIB topic defined within a topicspace on the service integration bus.

Forward Routing Path

A comma-separated list of bus destinations that a message should pass through after it has been delivered to the bus destination to which the producer is attached.

Data type String
Range A comma-separated list of bus destination names; for example:
sidestnA, sidestnB, sidestnC

Non persistent QOS

The acceptable reliability for message delivery, as a quality of service, for non-persistent JMS messages.

If you do not specify a value for this property, the destination uses the quality of service specified for the connection factory.

Data type Integer
Default Express
Range
Express
Messages are delivered on a "best-effort" basis, and it is acceptable if some are lost or discarded by the system; for example, due to a messaging engine failing or lacking resources.
Reliable
Messages can be lost if a messaging engine fails, but are not lost under normal operating conditions. The messaging engine does not discard messages due to lack of resources, but exerts back pressure on producers or spills messages to disk to relieve resource constraints.
As connection
The corresponding value configured for the connection factory is used.

Time before expiration

The time in milliseconds before messages on this destination expire.

Data type Integer
Default 0
Range

Producer mediation

The name of a mediation to be applied when this JMS destination is being used as a message producer

Data type String
Default Null

Consumer mediation

The name of a mediation to be applied when this JMS destination is being used as a message consumer

Data type String
Default Null

Name

The name by which the queue is known for administrative purposes.

Data type String

JNDI name

The JNDI name that is used to bind the queue into the application server's 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

Name

The name by which the topic is known for administrative purposes.

Data type String

JNDI name

The JNDI name that is used to bind the topic into the application server's 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 the resource, for administrative purposes.

Data type String
Default Null

Category

A category used to classify or group this resource, for your administrative records.

Data type String
Default Null

JNDI name

The JNDI name that is used to bind the resource 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

Persistence

Whether all messages sent to the destination are persistent, non-persistent, or have their persistence defined by the application.

Data type Enum
Units Not applicable
Default APPLICATION_DEFINED
Range
Application defined
Messages on the destination have their persistence defined by the application that put them onto the queue.
Queue defined
[WebSphere MQ JMS queue destination only] Messages on the destination have their persistence defined by the WebSphere MQ queue definition properties.
Persistent
Messages on the destination are persistent.
Non persistent
Messages on the destination are not persistent.

Priority

Whether the message priority for this destination is defined by the application or the Specified priority property

Data type Enum
Units Not applicable
Default APPLICATION_DEFINED
Range
Application defined
The priority of messages on this destination is defined by the application that put them onto the destination.
Specified
The priority of messages on this destination is defined by the Specified priority property. If you select this option, you must define a priority on the Specified priority property.

Specified priority

If the Priority property is set to Specified, type here the message priority for this queue, in the range 0 (lowest) through 9 (highest)

If the Priority property is set to Specified, messages sent to this queue have the priority value specified by this property.

Data type Integer
Units Message priority level
Default Null
Range 0 (lowest priority) through 9 (highest priority)

Expiry

Whether the expiry timeout for this destination is defined by the application or the Specified expiry property, or messages on the destination never expire (have an unlimited expiry timeout)

Data type Enum
Units Not applicable
Default APPLICATION_DEFINED
Range
Application defined
The expiry timeout for messages on this destination is defined by the application that put them onto the destination.
Specified
The expiry timeout for messages on this destination is defined by the Specified expiry property.If you select this option, you must define a timeout on the Specified expiry property.
Unlimited
Messages on this destination have no expiry timeout, so those messages never expire.

Specified expiry

If the Expiry timeout property is set to Specified, type here the number of milliseconds (greater than 0) after which messages on this queue expire

Data type Integer
Units Milliseconds
Default Null
Range Greater than or equal to 0
  • 0 indicates that messages never timeout
  • Other values are an integer number of milliseconds

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.

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. You 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. See the following table for details.

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

Name

The name by which the JMS provider is known for administrative purposes.

Data type String
Default Null

Reference topic

Terms of Use | Feedback

Last updated: 5 Oct 2005
http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.pmc.nd.doc\share\jms_entities.html

© Copyright IBM Corporation 2004, 2005. All Rights Reserved.
This information center is powered by Eclipse technology. (http://www.eclipse.org)