JMS activation specification [Settings]

A JMS activation specification is associated with one or more message-driven beans and provides the configuration necessary for them to receive messages.

To view this page in the console, click one of the following paths:

• Resources -> JMS -> Activation specifications -> activation_specification_name
• Resources -> JMS -> JMS providers -> a_messaging_provider -> [Additional Properties] Activation specifications -> activation_specification_name

Use this panel to browse or change the configuration properties of the selected JMS activation specification for use with the default messaging provider.

Create a JMS activation specification to use a message-driven bean to communicate with the default messaging provider through Java EE Connector Architecture (JCA) 1.5. JCA provides Java connectivity between application servers such as WebSphere Application Server, and enterprise information systems. It provides a standardized way of integrating JMS providers with Java EE application servers, and provides a framework for exchanging data with enterprise systems, where data is transferred in the form of messages.

All the activation specification configuration properties apart from the Name, JNDI name, Destination JNDI name or Destination lookup, and Authentication alias are overridden by appropriately named activation-configuration properties in the deployment descriptor of an associated EJB 2.1 or later message-driven bean. For an EJB 2.0 message-driven bean, the Destination type, Subscription durability, Acknowledge mode and Message selector properties are overridden by the corresponding elements in the deployment descriptor. For either type of bean, the Destination JNDI name or Destination lookup property can be overridden by a value specified in the message-driven bean bindings.

The activation specification properties influence how the default messaging provider chooses the messaging engine to which the message-driven bean application connects. By default, the environment automatically connects applications to an available messaging engine on the bus. However we can specify extra configuration details to influence the connection process; for example to identify special bootstrap servers, or to limit connection to a subgroup of available messaging engines, or to improve availability or performance, or to ensure sequential processing of messages received. For information about why and how to do this, see the topic How JMS applications connect to a messaging engine on a bus.

Configuration tab

The Configuration tab shows configuration properties for this object. These property values are preserved even if the runtime environment is stopped then restarted.

General Properties

Scope

Highest topological level at which application servers can use this resource object.

Information	Value
Required	No
Data type	String

Provider

Specifies a JMS provider, which enables asynchronous messaging based on the Java Message Service (JMS). It provides J2EE connection factories to create connections for specific JMS queue or topic destinations. JMS provider administrative objects are used to manage JMS resources for the associated JMS provider.

Information	Value
Required	No
Data type	String

Name

The required display name for the resource.

Information	Value
Required	Yes
Data type	String

JNDI name

The JNDI name for the resource.

Type the JNDI name specified in the bindings for message-driven beans associated with this activation specification.

Information	Value
Required	Yes
Data type	String

Description

An optional description for the resource.

Information	Value
Required	No
Data type	Text area

Destination type

Whether the message-driven bean uses a queue or topic destination.

Information	Value
Required	Yes
Data type	drop-down list
Range	Queue The message-driven bean uses a JMS queue. The JNDI name of the JMS queue is specified on the Destination JNDI name property. Topic The message-driven bean uses a JMS topic. The JNDI name of the JMS topic is specified on the Destination JNDI name property.

Destination lookup

JNDI Name of destination

Type the JNDI name that the message-driven bean uses to look up the JMS destination in the JNDI namespace.

Select the type of destination on the Destination type property.

For resource adapters that support JMS we must associate javax.jms.Destinations with an activation specification, such that the resource adapter can service messages from the JMS destination. In this case, the administrator configures a J2C Administered Object that implements the javax.jms.Destination interface and binds it into JNDI.

We can configure a J2C Administered Object to use an ActivationSpec class that implements a setDestination(javax.jms.Destination) method. In this case, we can specify the Destination lookup (that is, the JNDI name for the J2C Administered object that implements the javax.jms.Destination).

During application start up, when the activation specification is being initialized as part of endpoint activation, the server uses the Destination lookup to look up the destination administered object then set it on the activation specification instance.

The Destination lookup property is referred to as Destination JNDI name in the earlier versions of WAS. In the JMS 2.0 specification, the property name is changed to Destination lookup for the message-driven bean (MDB) to receive messages from the JMS Queue or JMS topic.

Information	Value
Required	Yes
Data type	String

Connection factory lookup

JNDI name of the connection factory.

Type JNDI name of the connection factory that the message-driven bean uses to look up the connection factory properties and overwrite them in activation specification properties.

When the connection factory lookup is defined in the activation specification as the JNDI name, the connection factory properties take precedence over the properties defined in the activation specification configuration. For example, a client ID set as part of the connection factory JNDI takes precedence over the client ID defined in the activation specification configuration properties.

Information	Value
Required	Yes
Data type	String

Message selector

The JMS message selector used to determine which messages the message-driven bean receives. The value is a string used to select a subset of the available messages. The syntax is based on a subset of the SQL 92 conditional expression syntax, as described in the JMS specification. Refer to the information center for more information.

For example:

JMSType='car' AND color='blue' AND weight>2500

The selector string can refer to fields in the JMS message header and fields in the message properties. Message selectors cannot reference message body values.

A null value (an empty string) indicates that there is no message selector for the message consumer.

Information	Value
Required	No
Data type	String

Bus name

The name of the bus to connect to.

Type the name of the service integration bus to which connections are made. This must be the name of the bus on which the destination identified by the Destination lookup property is defined.

Information	Value
Required	No
Data type	Custom

Acknowledge mode

How the session acknowledges any messages it receives.

The acknowledge mode indicates how a message received by a message-driven bean should be acknowledged.

The acknowledgment is sent when the message is deleted.

If we have a non-transactional message-driven bean, the system either deletes the message when the bean starts, or when the bean completes. If the bean generates an exception, and therefore does not complete, the system takes one of the following actions:

• If the system is configured to delete the message when the bean completes, then the message is despatched to a new instance of the bean, so the message has another opportunity to be processed.

• If the system is configured to delete the message when the bean starts, then the message is lost.

The message is deleted when the bean starts if the quality of service is set to Best effort nonpersistent. For all other qualities of service, the message is deleted when the bean completes.

Information	Value
Required	No
Data type	drop-down list
Range	Auto-acknowledge The session automatically acknowledges the delivery of a message. Duplicates-ok auto-acknowledge The session lazily acknowledges the delivery of messages, which can improve performance, but can lead to a message-driven bean receiving a message more than once.

Target

The name of a target that identifies a group of messaging engines. Type of target using the Target type property.

Information	Value
Required	No
Data type	String

Target type

The type of target named in the Target property.

Information	Value
Required	No
Data type	drop-down list
Range	Bus member name The name of a bus member. This option retrieves the active messaging engines that are hosted by the named bus member (an application server or server cluster). Custom messaging engine group name The name of a custom group of messaging engines (that form a self-declaring cluster). This option retrieves the active messaging engines that have registered with the named custom group. Messaging engine name The name of a messaging engine. This option retrieves the available endpoints used to reach the named messaging engine.

Target significance

This property specifies the significance of the target group.

Information	Value
Required	No
Data type	drop-down list
Range	Preferred It is preferred that a messaging engine is selected from the target group. A messaging engine in the target group is selected if one is available. If a messaging engine is not available in the target group, a messaging engine outside the target group is selected if available in the same service integration bus. Required It is required that a messaging engine is selected from the target group. A messaging engine in the target group is selected if one is available. If a messaging engine is not available in the target group, the connection process fails.

Target inbound transport chain

The name of the inbound transport chain that the application should target when connecting to a messaging engine in a separate process to the application. If a messaging engine in another process is chosen, a connection can be made only if the messaging engine is in a server that runs the specified inbound transport chain. Refer to the information center for more information.

If the selected messaging engine is in the same server as the application, a direct in-process connection is made and this transport chain property is ignored.

The transport chains represent network protocol stacks operating within a server. The name we specify must be one of the transport chains available in the server that hosts the messaging engine, as listed on the Servers -> Server Types -> WebSphere application servers -> server -> [Server messaging] Messaging engine inbound transports panel. The following transport chains are provided, but we can define our own transport chains on that panel.

InboundBasicMessaging

This is a connection-oriented protocol that uses a standard TCP/IP connection (JFAP-TCP/IP). It includes support for two-phase transactional (remote XA) flows, so that a message producer or consumer, running on a client or server system, can participate in a global transaction managed on that client or server system. The specific use for the XA flows is to support access from an application running in one server to a messaging engine on second server, perhaps because the first server does not have a suitable messaging engine. If the remote XA flows are used, a transaction coordinator must be available local to the application.

InboundSecureMessaging

This is the InboundBasicMessaging protocol wrapped in SSL.

For more information about using this property with other connection factory properties for workload management of connections, see the topic Administrative properties for JMS connections to a bus.

Information	Value
Required	No
Data type	String

Provider endpoints

A comma-separated list of endpoint triplets, with the syntax hostName:portNumber:chainName, used to connect to a bootstrap server. For example Merlin:7276:BootstrapBasicMessaging,Gandalf:5557:BootstrapSecureMessaging.

Provider endpoints are not used unless the specified bus cannot be found in the local cell. Message-driven bean (MDB) applications first attempt to connect the specified bus in the local cell. If this attempt fails, provider endpoints are used to allow the applications to consume messages from a remote cell.

If the host name is not specified, localhost is used as a default value.

If the port number is not specified, 7276 is used as the default value.

If the protocol is not specified, a predefined chain such as BootstrapBasicMessaging is used as the default value.

Information	Value
Required	No
Data type	Text area

Maximum batch size

The maximum number of messages received from the messaging engine in a single batch.

The maximum number of messages in a single batch delivered serially to a single message-driven bean instance. Batching of messages can improve performance particularly when used with Acknowledge mode set to Duplicates-ok auto-acknowledge. If message-ordering must be retained across failed deliveries, set the batch size to 1.

Information	Value
Required	No
Data type	Integer
Range	1 through 2147483647

Maximum concurrent MDB invocations per endpoint

The maximum number of endpoints to which messages are delivered concurrently.

Increasing this number can improve performance but can increase the number of threads in use at any one time. Increase the SIBJMSRAThreadPool thread pool. If message ordering must be retained across failed deliveries, set the maximum concurrent endpoints to 1. Message ordering applies only if the destination that the message-driven bean is consuming from is not a partitioned destination. Partitioned destinations are used in a workload sharing scenario in a cluster.

Information	Value
Required	No
Data type	Integer
Range	1 through 2147483647

Automatically stop endpoints on repeated message failure

These parameters enable an endpoint to stop automatically when the number of sequentially failing messages reaches a limit specified. This helps to distinguish between one or two messages that fail because of problems with the messages themselves, and a system resource problem that results in many sequentially failing messages.

Stopping the endpoint reduces the number of messages being moved unnecessarily to an exception destination when the problem is not caused by messages that are failing to be processed.

When an endpoint is stopped automatically, its Status on the administrative console panel is red. It must be restarted manually by clicking Resume.

After an endpoint is restarted, any failing messages that caused the endpoint to be stopped are retried. If they continue to fail they are moved to an exception destination, if configured.

Enable

Enable automatic stopping of an endpoint based on the parameters below.

Information	Value
Required	No
Data type	Boolean

Sequential failed message threshold

The endpoint will be stopped when the number of sequentially failing messages reaches the configured limit. Due to processing dependencies in the MDB the actual number of messages processed may exceed this value.

This property is not enabled unless the Automatically stop endpoints on repeated message failure property is enabled.

Information	Value
Required	No
Data type	Integer

Delay between failing message retries

Any message that fails to be processed by the MDB but has not reached its maximum failed delivery limit will only be retried after this period of time (in milliseconds) has passed. Other messages may be tried during this period, unless the sequential failure threshold and the maximum concurrency is set to 1.

Set a delay between failing message retries reduces the number of messages unnecessarily moved to the exception destination before the MDB is stopped. To minimize the number of messages that are moved, make this delay greater than the expected time interval between messages arriving on the destination.

This property is not enabled unless the Automatically stop endpoints on repeated message failure property is enabled.

Information	Value
Required	No
Data type	Integer
Range	The time in milliseconds. A value of 0 indicates no delay between retries.

Subscription durability

Whether a JMS topic subscription is durable or nondurable

Usually, only one application at a time can have a consumer for a particular durable subscription. Enable you to override this behavior, to enable a durable subscription to have multiple simultaneous consumers.

Information	Value
Required	No
Data type	drop-down list
Range	Durable The messaging provider stores messages while the message-driven bean is not available, and delivers the messages when the message-driven bean becomes available again. Nondurable The messaging provider does not store and redeliver messages if a message-driven bean is not available.

Subscription name

The subscription name needed for topic subscriptions. Required field when using a topic subscription.

Each JMS subscription is identified by a subscription name (specified on this property). A JMS connection also has an associated client identifier (specified on the Client identifier property), which is used to associate a connection and its objects with the list of messages (on the subscription) that is maintained by the JMS provider for the client.

This subscription name must be unique within a given client identifier.

Information	Value
Required	No
Data type	String

Client identifier

The JMS client identifier needed for topic subscriptions on all connections created using this activation specification.

The value specified is a unique identifier for a client (message-driven bean). The client identifier is used to associate a client connection with the list of messages (on a subscription) that the messaging provider keeps for the client. When a client becomes available again, after a being unavailable, the messaging provider uses the client identifier to redeliver stored messages to the correct client.

Information	Value
Required	No
Data type	String

Subscription home

The name of the messaging engine used to store messages delivered to subscriptions for objects created from this JMS activation specification. This is a required field when using a topic subscription.

Administrators can manage the runtime state of subscriptions through publication points for this messaging engine.

For shared nondurable subscription, the messaging engine name value under the Subscription home field is treated as the target messaging engine. So any messaging engine name that is defined under the Target field is ignored.

Information	Value
Required	No
Data type	String

Pass message payload by reference

When large object messages or bytes messages are sent, the cost in memory and processor use of serializing, deserializing, and copying the message payload can be significant.If we enable the pass message payload by reference properties on a connection factory or activation specification, you tell the default messaging provider to override the JMS 1.1 specification and potentially reduce or bypass this data copying.

CAUTION:

The parts of the JMS Specification that are bypassed by these properties are defined to ensure message data integrity. Any of our JMS applications that use these properties must strictly follow the rules described in the topic Why and when to pass the JMS message payload by reference, or you risk losing data integrity.

Applications that use this activation specification to receive messages must obey the following rule:

• The application does not modify the data object obtained from a JMS object message. The data object is treated as read only.

When enabled, Object Messages received through this activation spec will only have their message data serialized by the system when absolutely necessary. The data obtained from those messages must be treated as readOnly by applications.

Information	Value
Required	No
Data type	Boolean

Applications resending messages that were originally received using this activation specification must obey the following rules:

• The application can replace the data object in a JMS object message, provided that the data object has not yet been set in the message. The application does not modify or replace the data object after it is set in the message.

• The application can replace the byte array in a JMS bytes message, but only using a single call to writeBytes(byte[]), and provided that the byte array has not yet been set in the message. The application does not modify or replace the byte array after it is set in the message.

When enabled, Object/Bytes Messages forwarded through this activation specification that have their payload modified will not have the data copied when it is set into the message and the system will only serialize the message data when absolutely necessary. Applications sending such messages must not modify the data once it has been set into the message.

Information	Value
Required	No
Data type	Boolean

Share durable subscriptions

Controls whether or not subscriptions are shared across connections with members of a server cluster.

Usually, only one session at a time can have a TopicSubscriber for a particular durable subscription. Enable you to override this behavior, to enable a durable subscription to have multiple simultaneous consumers, one on each application server in the server cluster.

Information	Value
Required	No
Data type	drop-down list
Range	In cluster Allows sharing of durable subscriptions when connections are made from within a server cluster. Always shared Durable subscriptions can be shared across connections. Never shared Durable subscriptions are never shared across connections.

Share data source with CMP

Allow sharing of connections between JMS and container-managed persistence (CMP) entity beans.

This option is used as part of the task to enable container-managed persistence (CMP) entity beans to share the database connections used by the data store of a messaging engine. This has been estimated as a potential performance improvement of 15% for overall message throughput, but can only be used for entity beans connected to the application server containing the messaging engine. This option must not be enabled for a messaging engine that uses file store as its data store.

For more information about using this option, see the topic Enabling CMP entity beans and messaging engine data stores to share database connections.

Information	Value
Required	No
Data type	Boolean

Read ahead

Read ahead is an optimization that preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests.

Messages assigned to a consumer are locked on the server and cannot be consumed by any other consumers for that destination. Messages assigned to a consumer, but not consumed before that consumer is closed, are subsequently unlocked on the server and then available for receipt by other consumers.

We can override this property for individual JMS destinations by setting the Read ahead property on the JMS destination.

Information	Value
Required	No
Data type	drop-down list
Range	Default The message provider preemptively assigns messages to consumers on nondurable subscriptions and unshared durable subscriptions. That is, read ahead optimization is turned on only when there can only be a single consumer. Enabled The messaging provider preemptively assigns messages to consumers. This improves the time taken to satisfy consumer requests. Disabled The messaging provider does not preemptively assign messages to consumers.

Always activate MDBs in all servers

This property is only used when the MDB application is running on a server that is a member of the bus that the application is targeting. It has no effect when the MDB is running on a server that is not a member of the target bus.

If the MDB application is running on a server that is a member of the target bus, enabling this option allows the MDB application to process messages whether or not the server also hosts a running messaging engine. If this option is not enabled, then MDB applications on servers that do not have a local ME running do not process messages.

For MDB applications connecting to a cluster bus member, we can also use this option to enable either of the following additional configurations:

• All servers in the cluster can receive messages from the MDB application, to make full use of the processing power in the cluster.
• Just one server at a time can receive messages from the MDB application, to ensure sequential processing of the messages.

To enable all servers in the cluster to receive messages from the MDB application, select this option. To enable just one server at a time to receive messages from the MDB application, check that this option is not selected and select the receive exclusive option on the destination.

See topic How a message-driven bean connects in a cluster.

Information	Value
Required	No
Data type	Boolean

Retry interval

The delay (in seconds) between attempts to connect to a messaging engine, both for the initial connection, and any subsequent attempts to establish a better connection.

Information	Value
Required	No
Data type	Integer
Range	1 through 2147483647

Authentication alias

The name of a J2C authentication alias used for component-managed authentication of connections to the service integration bus.

A Java EE Connector Architecture (JCA) authentication alias specifies the user ID and password used to authenticate the creation of a new connection to the JMS provider.

The user name and password custom properties fields must be left unspecified if the authentication alias field used. Authentication alias properties set as part of application deployment take precedence over properties set on an activation specification administrative object.

Only the authentication alias is ever written to file in an unencrypted form, even for purposes of transaction recovery logging. The security service is used to protect the real user name and password.

During application startup, when the activation specification is being initialized as part of endpoint activation, the server uses the authentication alias to retrieve the real user name and password from security then set it on the activation specification instance.

Information	Value
Required	No
Data type	drop-down list

Related Items

JAAS - J2C authentication data

List of user identities and passwords for Java 2 connector security to use.

Buses

A service integration bus supports applications using message-based and service-oriented architectures. A bus is a group of interconnected servers and clusters that have been added as members of the bus. Applications connect to a bus at one of the messaging engines associated with its bus members.