JMS activation specification [Settings]

A JMS activation spec 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 spec for use with the default messaging provider.

You create a JMS activation spec if you want 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 appservers such as WAS, and enterprise information systems. It provides a standardized way of integrating JMS providers with Java EE appservers, and provides a framework for exchanging data with enterprise systems, where data is transferred in the form of messages.

All the activation spec configuration properties apart from Name, JNDI name, Destination JNDI name, 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 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 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. See the information center task descriptions for information about how to apply configuration changes to the runtime environment.

 

General Properties

 

Scope

Specifies the highest topological level at which appservers can use this resource object.

Required	No
Data type	Text

 

Provider

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

Required	No
Data type	Text

 

Name

The required display name for the resource.

Required	Yes
Data type	Text

 

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.

Required	Yes
Data type	Text

 

Description

An optional description for the resource.

Required	No
Data type	Text area

 

Destination type

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

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 JNDI name

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.

Required	Yes
Data type	Text

 

Message selector

The JMS message selector used to determine which messages the message-driven bean receives. The value is a string that is 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.

Required	No
Data type	Text

 

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 JNDI name property is defined.

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

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. Specify the type of target using the Target type property.

Required	No
Data type	Text

 

Target type

The type of target named in the Target property.

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 appserver 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 that can be used to reach the named messaging engine.

 

Target significance

This property specifies the significance of the target group.

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 you specify must be one of the transport chains available in the server that hosts the messaging engine, as listed on the panel...

Servers > Server Types > WebSphere application servers > server_name > [Server messaging] Messaging engine inbound transports

The following transport chains are provided, but we can define your 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.

See about using this property with other connection factory properties for workload management of connections, see Administrative properties for JMS connections to a bus.

Required	No
Data type	Text

 

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.

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.

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 that are in use at any one time. 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.

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 that you specify. 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 admin 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.

Required	No
Data type	Check box

 

Sequential failed message threshold

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

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

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

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

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. This property enables you to override this behavior, to enable a durable subscription to have multiple simultaneous consumers.

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 durable topic subscriptions. Required field when using a durable topic subscription. Each JMS durable 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 durable subscription) that is maintained by the JMS provider for the client.

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

Required	No
Data type	Text

 

Client identifier

The JMS client identifier needed for durable 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 durable 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.

Required	No
Data type	Text

 

Durable subscription home

The name of the messaging engine used to store messages delivered to durable subscriptions for objects created from this JMS activation specification. This is a required field when using a durable topic subscription. Administrators can manage the runtime state of durable subscriptions through publication points for this messaging engine.

Required	No
Data type	Text

 

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 you 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 spec 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 the JMS applications that use these properties must strictly follow the rules that are described in Why and when to pass the JMS message payload by reference, or you risk losing data integrity.

 

Applications that use this activation spec 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.

Required	No
Data type	Check box

 

Applications resending messages that were originally received using this activation spec 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 by 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 spec 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.

Required	No
Data type	Check box

 

Share durable subscriptions

Controls whether or not durable 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. This property enables you to override this behavior, to enable a durable subscription to have multiple simultaneous consumers, one on each appserver in the server cluster.

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 appserver that contains the messaging engine.

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

Required	No
Data type	Check box

 

Read ahead

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

Messages that are assigned to a consumer are locked on the server and cannot be consumed by any other consumers for that destination. Messages that are 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.

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

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 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 How a message-driven bean connects in a cluster.

Required	No
Data type	Check box

 

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.

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 that is used to authenticate the creation of a new connection to the JMS provider.

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.

---

Last updated Dec 15, 2010 8:14:22 PM CST