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.
You create a JMS activation specification 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 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 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
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 task descriptions for information about how to apply configuration changes to the runtime environment.
General Properties
Scope
Specifies the 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.
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 |
|
Destination JNDI name
JNDI Name of destination
Select the type of destination on the Destination type property.
For resource adapters that support JMS you 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.
You 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.
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 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 documentation for more information.
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.
Information | Value |
---|---|
Required | No |
Data type | Custom |
Acknowledge mode
How the session acknowledges any messages it receives.
The acknowledgment is sent when the message is deleted.
- 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 |
|
Target
The name of a target that identifies a group of messaging engines. Specify the 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 |
|
Target significance
This property specifies the significance of the target group.
Information | Value |
---|---|
Required | No |
Data type | drop-down list |
Range |
|
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 documentation 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.
- 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.
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.
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.
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.
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 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.
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 following parameters.
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.
Setting 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
Information | Value |
---|---|
Required | No |
Data type | drop-down list |
Range |
|
Subscription name
The subscription name needed for durable topic subscriptions. Required field when using a durable topic subscription.
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 durable topic subscriptions on all connections created using this activation specification.
Information | Value |
---|---|
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.
Information | Value |
---|---|
Required | No |
Data type | String |
Pass message payload by reference
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 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 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 durable subscriptions are shared across connections with members of a server cluster.
Information | Value |
---|---|
Required | No |
Data type | drop-down list |
Range |
|
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. 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 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.
You 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 |
|
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.
- 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.
For more information, see the 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 Platform, Enterprise Edition (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.
The user name and password custom properties fields must remain 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
- 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.