Network Deployment (Distributed operating systems), v8.0 > Reference > Sets


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:

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

You 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 WAS, 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 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 your message-driven bean application connects. By default, the environment automatically connects applications to an available messaging engine on the bus. However you 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

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.

Required No
Data type String


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 administrative objects are used to manage JMS resources for the associated JMS provider.

Required No
Data type String


Name

The required display name for the resource.

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.

Required Yes
Data type String


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.

For resource adapters that support JMS 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, you can specify the destination JNDI name (that is, the JNDI name for the J2C Administered object that implements the javax.jms.Destination).

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

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.

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

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 String


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 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 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 Servers -> Server Types -> WebSphere application servers -> server_name

-> [Server messaging] Messaging engine inbound transports panel. The following transport chains are provided, but you 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.
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.

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.

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.

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

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.

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.

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 String


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 String


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 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 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 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 your 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:

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 Boolean


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

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.

Required No
Data type Boolean


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

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

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

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, you can also use this option to enable either of the following additional configurations:

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.

For more information, see the topic How a message-driven bean connects in a cluster.

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.

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.

Required No
Data type drop-down list


Related Items

JAAS - J2C authentication data

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

Pass message payload by reference: Example code for producer and consumer applications
Pass message payload by reference: Usage scenarios and example code for forwarding applications
Why and when to pass the JMS message payload by reference
How JMS applications connect to a messaging engine on a bus
How a message-driven bean connects in a cluster
Service integration configurations
Pass message payload by reference: Potential benefits for each processing step
Configure MDB throttling for the default messaging provider
Enable CMP entity beans and messaging engine data stores to share database connections
Configure an activation specification for the default messaging provider
Configure a connection to a non-default bootstrap server
Administrative console buttons
Administrative console preferences

+

Search Tips   |   Advanced Search