Configuring the Eclipse Amlen resource adapter for inbound communication

To configure inbound communication, define the properties of one or more ActivationSpec objects.

The properties of an ActivationSpec object determine how a Message-Driven bean (MDB) receives JMS messages from Eclipse Amlen. These properties are used to create all JMS objects that are necessary to receive messages, including connection, session, and consumer objects.

Complete the following steps to create and configure a new ActivationSpec by using the WebSphere® Application Server panels.
  1. Log on to the WebSphere Application Server administrative console.
  2. Click Resources > Resource Adapters > J2C activation specifications.
  3. Optional: Change the Scope setting if required. The default setting is ALL.
  4. Click New and complete the Name field and the JNDI name field for your activation specification.
  5. Click Apply.
  6. Click the J2C activation specification custom properties link in the Additional Properties panel. You can then edit the properties of the ActivationSpec object.
  7. Click Save to save your changes.

Table 1 lists the properties of an ActivationSpec object that are used to configure the Eclipse Amlen resource adapter for inbound communication.

Table 1. ActivationSpec object propertiesList of the properties of an ActivationSpec object that are used to configure the Eclipse Amlen resource adapter for inbound communication.

properties of an ActivationSpec object that are used to configure the resource adapter.
Name of property Type Valid values Default value Description
acknowledgeMode String Auto-acknowledge, Dups-ok-acknowledge Auto-acknowledge The mode for acknowledging received messages.

When Auto-acknowledge is specified, the session automatically acknowledges each message that is received by the application. When Dups-ok-acknowledge is specified, the session acknowledges the messages that are received by the application at times it selects.
clientId String Any valid Unicode string null

The client ID for this connection.

Setting client ID is optional in most cases, but is required for non-shared, durable subscriptions. If clientId is set, it must be unique for all connections to an Eclipse Amlen server. If clientId is not set (and is not required to be set), then the Eclipse Amlen JMS client automatically creates a client ID.

The Eclipse Amlen JMS client allows any valid Unicode string to be used as a client ID. However, you might prefer to use displayable characters. System generated client IDs start with an underscore (_), therefore avoid using an underscore as an initial character to prevent conflicts. Client IDs that start with two underscores (__) are reserved for system use. Therefore, you cannot use client IDs that start with two underscores.
clientMessageCache Numeric -1, or 0 and above -1

The maximum number of cached messages for each consumer.

Eclipse Amlen has built-in default cache sizes. Use the default setting of -1 to access these default settings. When -1 is specified, the cache size is set to 1000 for unshared topic subscriptions and to 0 (no caching) otherwise.

Using larger values for clientMessageCache can improve throughput. However, in the cases of queues with multiple consumers, and shared topic subscriptions, use the value of 0 to distribute messages evenly across consumers.

concurrentConsumers Numeric Value can be in the range of 1 - 100 1

The maximum number of consumers on this connection.

For topics, this value must not exceed 1, unless subscriptionShared is set to Shared.
convertMessageType String auto, bytes, text auto

The action to take when a message is converted to JMS from a source that does not indicate the message type.

If the message comes from JMS, then this property is not used. When bytes is specified, then messages are converted to BytesMessage. When text is specified, then messages are converted to TextMessage. When auto is specified, then the JMS client automatically determines whether to convert the message to BytesMessage or to TextMessage.
destination String Any valid Unicode string null

The name of the topic or queue from which messages are received.

Specify either the destination and destinationType properties or the destinationLookup property. If the destinationLookup property is set, then the values that are specified for the destination and destinationType properties are ignored.

destinationLookup String Any valid Unicode string null

The name of a JNDI object that represents the Eclipse Amlen topic or queue from which messages are received.

Specify either the destination and destinationType properties or the destinationLookup property. If the destinationLookup property is set, then the values that are specified for the destination and destinationType properties are ignored.

To use destinationLookup, configure the administered object for this destination. For more information, see Configuring the Eclipse Amlen resource adapter for administered objects.
destinationType String javax.jms.Topic, javax.jms.Queue null

The type of destination for a specified destination value.

This property and the destination property must be specified if the destinationLookup property is not set. If the destinationLookup property is set, then the values that are specified for the destination and destinationType properties are ignored.
enableRollback String true, false false

Specifies how messages are handled when onMessage() fails and the MDB is configured to run with an unspecified transaction context.

When a MDB runs in an unspecified transaction context, enableRollback determines how to handle a message if an exception is generated from the MDB onMessage() method.

A MDB runs with an unspecified transaction context when configured in one of the following ways:
  • The MDB is configured with transaction-type, bean
  • The MDB is configured with transaction-type, container and the transaction-attribute is NotSupported.

If set to false, the message is consumed even if the MDB fails. If set to true, the message is rolled back and redelivered if the MDB fails.

If the MDB is configured with transaction-type container and the transaction-attribute is Required, the enableRollback setting is ignored.

maxDeliveryFailures Numeric -1, or 0 and above -1

The maximum number of onMessage() failures that are allowed for the MDB. The message endpoint is paused after the specified failure count is reached. The default value of -1 indicates that the failure count is ignored and that the message endpoint is never paused.

The MDB is responsible for handling errors in the onMessage() method. However, transient system issues might cause unexpected failures to occur. Configuring this value allows the message endpoint to be paused so that the WebSphere administrator can investigate and resolve any issues. After the issues are resolved, the message endpoint can be resumed. If system issues do not explain the unexpected failures in onMessage(), then it is possible that the MDB does not handle poison messages. For more information about handling poison messages, see Poison messages.

The failure count is a cumulative value and it can include failures for more than one message. The count is reset to 0 for an MDB only if both of the following conditions are true;
  • A message is successfully processed in onMessage().
  • No failures occurred in onMessage() during the previous 30 seconds.

If the specified destination is a topic, any message that is published while the MDB is paused is lost unless the MDB is configured to use a durable subscription. If the MDB uses a durable subscription or if the destination is a queue, it is important to restart the MDB promptly after a pause. If the MDB is not restarted after a pause, a backlog of messages can accumulate on the Eclipse Amlen server.

Note: To resume the message endpoint in WebSphere Application Server, click Applications > Application Types > WebSphere enterprise applications and then select the application name. On the application panel, select the Runtime tab. Then, select Manage message endpoints.
messageSelector String A selector that is composed of valid Unicode characters null

A JMS message selector that specifies which messages are selected. The default value of null indicates that all messages are selected.
password String Any valid Unicode string null

The password for user authentication with Eclipse Amlen. Eclipse Amlen uses this value if user is specified.

port Numeric Value can be in the range of 1 - 65535 0

This default value must be changed.

The Eclipse Amlen TCP port to use for this connection.

If there are multiple Eclipse Amlen servers in the server properties list, then all servers use the same port.

protocol String tcp, tcps tcp

The transmit protocol for communication with Amlen.

A value of tcp indicates a non-secure connection. A value of tcps indicates a secure connection. If a secure connection is specified, then you must ensure that the WebSphere Application Server is correctly configured. For more information, see Transport Layer Security for the Eclipse Amlen resource adapter.
securityConfiguration String Any valid Unicode string null

The name of the WebSphere security configuration to use for this connection.

This value is only used if protocol is set to tcps. Use securityConfiguration only if you are not using the WebSphere Application Server default security configuration. For more information, see Transport Layer Security for the Eclipse Amlen resource adapter.
securitySocketFactory String Any valid Unicode string null

The name of the security socket factory that is used for establishing secure connections.

This value is only used if protocol is set to tcps. Use securitySocketFactory only if you are not using the WebSphere Application Server default security socket factory. For more information, see Transport Layer Security for the Eclipse Amlen resource adapter.
server String Any valid Unicode string null

This default value must be changed.

A space or comma delimited list of Eclipse Amlen host names or IP addresses. The resource adapter attempts to connect to each server in the list until a connection is established.

subscriptionDurability String Durable, NonDurable NonDurable

Specifies whether a topic subscription is durable. This value is ignored if the destination is a queue.

When set to Durable, subscriptionName must be set. When set to Durable with subscriptionShared set to NonShared, then clientId must also be set.

subscriptionName String Any valid Unicode string null

The name for a durable or shared subscription.

This value must be set for any durable or shared subscription. This value is ignored if the destination is a queue, or if the subscription is a non-durable unshared subscription.

subscriptionShared String Shared, NonShared NonShared

Specifies whether a subscription is shared between consumers or not.

This value is ignored if the destination is a queue. If set to Shared, then subscriptionName must be set. If set to NonShared with subscriptionDurability set to Durable, then clientId must be set.

traceLevel Numeric -1, or value can be in the range of 0 - 9 -1

The level of trace detail that is provided in the Eclipse Amlen JMS client and resource adapter output for this connection.

When set to -1, the trace level that is used for this connection is the ResourceAdapter defaultTraceLevel setting.

For example, WebSphere Application Server is started with defaultTraceLevel set to 4. If an MDB is then started that uses an activation specification with traceLevel set to -1, then the trace level for that MDB and associated activation specification is 4.

At level 0, there is no trace. At level 9, there is a detailed debug trace. As the trace level is increased, more trace is shown. Use trace levels of 5 or lower to minimize performance impact and generate a small amount of trace, including stack traces for all exceptions. Use trace levels of 6 - 9 for debugging. Higher log levels can result in a large amount of trace output and can affect performance.

Note: If the defaultTraceLevel is changed after the WebSphere Application Server is started, then any new or existing activation specifications and connection factories that are set to use -1 continue to receive and use the defaultTraceLevel that was in effect when the WebSphere Application Server started. The new defaultTraceLevel value is not used until the next time the application server is started.
user String Any valid Unicode string null

The user name for user authentication with Eclipse Amlen. Eclipse Amlen always uses this value if it is provided, unless a security profile is attached to the endpoint with UsePasswordAuthentication set to False.

Wildcards

Wildcards are supported for inbound communication when you use topics. For more information about wildcards, see Wildcards.