Managing messages with message endpoints

Manage message delivery for message-driven beans (MDB) that are deployed as message endpoints. The message endpoints are managed beans (MBeans) for inbound resource adapters that are compliant with Java™ Platform, Enterprise Edition (Java EE) Connector Architecture (JCA) Version 1.5.

About this task

The application server provides message endpoint MBeans to assist you in managing the delivery of a message to your message-driven beans that are acting as listeners on specific endpoints, which are destinations, and in managing the enterprise information system (EIS) resources that are utilized by these message-driven beans. Message-driven beans that are deployed as message endpoints are not the same as message-driven beans that are configured against a listener port. Message-driven beans that are used as message endpoints must be deployed using an ActivationSpecification that is defined within a resource adapter configuration for JCA Version 1.5.
With message endpoint MBeans, you can activate and deactivate specific endpoints within your applications to ensure that messages are delivered only to listening message-driven beans that are interacting with healthy EIS resources. This capability allows you to optimize the performance of your JMS applications in situations where an EIS resource is not behaving as expected. Message delivery to an endpoint typically fails when the message driven bean that is listening invokes an operation against a resource that is not healthy. For example, a messaging provider, which is an inbound resource adapter that is JCA Version 1.5 compliant, might fail to deliver messages to an endpoint when its underlying message-driven bean attempts to commit transactions against a database server that is not responding.
Note: Design your message-driven beans to delegate business processing to other enterprise beans. Do not access the EIS resources directly in the message-driven bean, but do so indirectly through a delegate bean.
Message endpoint MBeans alleviate two problems that are inherent to applications that provide message endpoints that access resources:
  • Failed messages require additional processing, such as delivering them to the listening endpoint again or redirecting them to alternate destinations that process failed messages. In addition, a resource adapter might redeliver a message to an endpoint an infinite number of times.
  • Message redirection requires the implementation of specialized destinations (queues and listeners) to process failed messages, as well as the logic to detect message failures. Message redirection is potentially error prone and computationally expensive due to its complexity.

The capability to deactivate (pause) and reactivate (resume) a specific message endpoint alleviates these problems by enabling the administrator to deactivate the endpoint from processing messages that are destined to fail. When the message endpoint is deactivated, you can repair the resource that is causing the problems and reactivate the endpoint to resume handling message requests. In the course of troubleshooting, you will not affect the resource adapter or the application that is hosting the endpoint.

If you are connecting to WebSphere® MQ, you can also use the WAS_EndpointInitialState custom property in the activation specification to make the message endpoint start out in a deactivated state. When you set this property to Inactive, the message-driven bean connects with the destination, but does not start receiving messages. Use this setting to automatically deactivate a message endpoint when you know that certain tasks must be completed, services must be started, or checks must be carried out, before message handling begins. You activate the message endpoint in the same way as you would reactivate a message endpoint that you paused during its operation.

Procedure

  1. Using the administrative console, navigate to the Message Endpoints panel for the application that is hosting the message endpoint.
    1. Select the Applications > Application Types > Websphere enterprise applications > application_name.
    2. Select the Runtime panel.
    3. Select Message Endpoints.
      The panel lists the set of message endpoints that are hosted by the application.
  2. Optional: Temporarily disable a message endpoint from handling messages and troubleshoot the problem.
    1. Deactivate the message endpoint by selecting the appropriate endpoint and clicking Pause.
    2. When the message endpoint is inactive, diagnose and repair the underlying cause of the delivery failures.
    3. Reactivate the message endpoint by selecting the appropriate endpoint and clicking Resume.
  3. Optional: Activate a message endpoint that started out in a deactivated state. Select the appropriate endpoint and click Resume.

Results

The behavior you will observe when you deactivate (pause) a message endpoint using the message endpoint MBean is dependent upon a variety of factors, including the resource adapter that manages the message endpoint, the configuration of the message endpoint and the application server topology. Some specific examples of interest are as follows:
  • MDB listening on a non-durable topic (dependent on configuration): The behavior that is implied by the deactivation (pause) of a message endpoint is often dependent upon the function that it is fulfilling. For example, if you have configured a message-driven bean to listen on a non-durable topic on the service integration bus, deactivating the message endpoint is analogous to stopping the application and will cause the subscription to be closed. This means that any messages that are published during the time that the message endpoint is paused will not be received by the message-driven bean.
  • Clustered message-driven bean (dependent on topology): In this scenario a message-driven bean application has been deployed to a cluster of servers. A given message endpoint MBean controls only the behavior of the MDB in one server from the cluster, so will cause only one server to stop processing messages. Depending upon the messaging configuration and the specific resource adapter in use the messages that would have been consumed by the paused message endpoint may be consumed by the active message endpoints in the cluster, or they may remain unconsumed until the paused message endpoint is resumed.
  • Clustered message-driven bean, a non-clustered queue: In this scenario, you have a cluster of servers with the same message-driven bean deployed to them. This is similar to the case, in which you have different message-driven beans with the same message selection criteria, except that in this case the message-driven beans are logically the same message-driven bean. Pausing the endpoint will cause only one of the servers to stop receiving messages, and the other message-driven beans will receive all the messages; none of the messages will be orphaned. To stop all of the endpoints, you must direct each server in the cluster to stop the local message endpoint.
  • Clustered message-driven bean, clustered queue: In this scenario, each message-driven bean is pulling messages from a different partition of the queue. Messaging through WebSphere MQ and the Service Integration Bus have similar, but different, capabilities. If you are using WebSphere MQ, then pausing one endpoint will not allow the other instances of the message-driven bean to receive the messages. In the Service Integration Bus, messages from a paused endpoint will be redirected to the other message-driven beans.