+

Search Tips   |   Advanced Search

Asynchronous beans

An asynchronous bean is a Java object or enterprise bean that can run asynchronously by a Java EE application, using the Java EE context of the asynchronous bean creator.

Deprecated feature: Asynchronous beans and CommonJ Timer and WorkManager are deprecated asynchronous scheduling facilities. Concurrency Utilities for Java EE replaces these deprecated scheduling facilities. v9 still supports asynchronous beans and CommonJ Timer and WorkManager. However, the v9 documentation focuses on Concurrency Utilities for Java EE. If we do not find the information about asynchronous beans that you seek in the v9 documentation, see the v8.5.5 documentation.depfeat

Asynchronous beans can improve performance by enabling a Java EE program to decompose operations into parallel tasks. Asynchronous beans support the construction of stateful, active Java EE applications. These applications address a segment of the application space of applications that require application threading, active agents within a server application, or distributed monitoring capabilities.

Asynchronous beans can run using the Java EE security context of the creator Java EE component. These beans also can run with copies of other Java EE contexts, such as:


Asynchronous bean interfaces

Four types of asynchronous beans exist:

Work object

There are two work interfaces that essentially accomplish the same goal. The legacy Asynchronous Beans work interface is com.ibm.websphere.asynchbeans.Work, and the CommonJ work interface is commonj.work.Work. A work object runs parallel to its caller using the work manager startWork or schedule method (startWork for legacy Asynchronous Beans and schedule for CommonJ). Applications implement work objects to run code blocks asynchronously.

Timer listener

This interface is an object that implements the commonj\timers\TimerListener interface. Timer listeners are called when a high-speed transient timer expires.

Alarm listener

An alarm listener is an object that implements the com.ibm.websphere.asynchbeans.AlarmListener interface. Alarm listeners are called when a high-speed transient alarm expires.

Event listener

An event listener can implement any interface. An event listener is a lightweight, asynchronous notification mechanism for asynchronous events within a single JVM. An event listener typically enables Java EE components within a single application to notify each other about various asynchronous events.


Supporting interfaces

Work manager

Work managers are thread pools that administrators create for Java EE applications. The administrator specifies the properties of the thread pool and a policy that determines which Java EE contexts the asynchronous bean inherits.

CommonJ Work manager

The CommonJ work manager is similar to the work manager. The difference between the two is that the CommonJ work manager contains a subset of the asynchronous beans work manager methods. Although CommonJ work manager functions in a Java EE 1.4 environment, each JNDI lookup of a work manager does not return a new instance of the WorkManager. All the JNDI lookup of work managers within a scope have the same instance.

Timer manager

Timer managers implement the commonj.timers.TimerManager interface, which enables Java EE applications, including servlets, EJB applications, and JCA Resource Adapters, to schedule future timer notifications and receive timer notifications. The timer manager for Application Servers specification provides an application-server supported alternative to using the J2SE java.util.Timer class, which is inappropriate for managed environments.

Event source

An event source implements the com.ibm.websphere.asynchbeans.EventSource interface. An event source is a system-provided object that supports a generic, type-safe asynchronous notification server within a single JVM. The event source enables event listener objects, which implement any interface to be registered.

Event source events

Every event source can generate its own events, such as listener count changed. An application can register an event listener object that implements the class com.ibm.websphere.asynchbeans.EventSourceEvents. This action enables the application to catch events such as listeners being added or removed, or a listener throwing an unexpected exception.

Additional interfaces, including alarms and subsystem monitors, are introduced in the Developing asynchronous scopes topic, which discusses some of the advanced applications of asynchronous beans.


Transactions

Every asynchronous bean method is called using its own transaction, much like container-managed transactions in typical enterprise beans. It is very similar to the situation when an EJB method is called with TX_NOT_SUPPORTED. The runtime starts a local transaction containment before invoking the method. The asynchronous bean method is free to start its own global transaction if this transaction is possible for the calling Java EE component. For example, if an enterprise bean creates the component, the method that creates the asynchronous bean must be TX_BEAN_MANAGED.

When we call an entity bean from within an asynchronous bean, for example, we must have a global transactional context available on the current thread. Because asynchronous bean objects start local transactional contexts, we can encapsulate all entity bean logic in a session bean that has a method marked as TX_REQUIRES or equivalent. This process establishes a global transactional context from which we can access one or more entity bean methods.

If the asynchronous bean method throws an exception, any local transactions are rolled back. If the method returns normally, any incomplete local transactions are completed according to the unresolved action policy configured for the bean. EJB methods can configure this policy using their deployment descriptor. If the asynchronous bean method starts its own global transaction and does not commit this global transaction, the transaction is rolled back when the method returns.


Access to Java EE component metadata

If an asynchronous bean is a Java EE component, such as a session bean, its own metadata is active when a method is called. If an asynchronous bean is a simple Java object, the Java EE component metadata of the creating component is available to the bean. Like its creator, the asynchronous bean can look up the java:comp namespace. This look up enables the bean to access connection factories and enterprise beans, just as it would if it were any other Java EE component. The environment properties of the creating component also are available to the asynchronous bean.

The java:comp namespace is identical to the one available for the creating component; the same restrictions apply. For example, if the enterprise bean or servlet has an EJB reference of java:comp/env/ejb/MyEJB, this EJB reference is available to the asynchronous bean. In addition, all of the connection factories use the same resource-sharing scope as the creating component.


Connection management

An asynchronous bean method can use the connections that its creating Java EE component obtained using java:comp resource references. (For more information on resource references, refer to the References topic). However, the bean method must access those connections using a get, use or close pattern. There is no connection caching between method calls on an asynchronous bean. The connection factories or datasources can be cached, but the connections must be retrieved on every method call, used, and then closed. While the asynchronous bean method can look up connection factories using a global JNDI name, this is not recommended for the following reasons:

For code examples that demonstrate both the correct and the incorrect ways to access connections from asynchronous bean methods, refer to the Example: Asynchronous bean connection management topic.


Deferred start of asynchronous beans

Asynchronous beans support deferred start by allowing serialization of Java EE service context information. The WorkWithExecutionContext createWorkWithExecutionContext(Work r) method on the WorkManager interface will create a snapshot of the Java EE service contexts enabled on the WorkManager. The resulting WorkWithExecutionContext object can then be serialized and stored in a database or file. This is useful when it is necessary to store Java EE service contexts such as the current security identity or Locale and later inflate them and run some work within this context. The WorkWithExecutionContext object can run using the startWork() and doWork() methods on the WorkManager interface.

All WorkWithExecutionContext objects must be deserialized by the same application that serialized it. All EJBs and classes must be present in order for Java to successfully inflate the objects contained within.


Deferred start and security

The asynchronous beans security service context might require Common Secure Interoperability v2 (CSIv2) identity assertion to be enabled. Identity assertion is required when a WorkWithExecutionContext object is deserialized and run to JAAS subject identity credential assignment. Review the following topics to better understand if we need to enable identity assertion, when using a WorkWithExecutionContext object:

There are also issues with interoperating with WorkWithExecutionContext objects from different versions of the product. Refer to the Interoperating with asynchronous beans topic.


JPA-related limitations

Use of asynchronous beans within a JPA extended persistence context is not supported.

A JPA extended persistence context is inconsistent with the scheduling and multi-threading capabilities of asynchronous beans and will not be accessible from an asynchronous bean thread.

Likewise, an asynchronous bean should not be created such that it takes a javax.persistence.EntityManager (or subclass) as a parameter since EntityManager instances are not intended to be thread safe.


Related:

  • Work managers
  • References in application deployment descriptor files
  • Local transaction containment
  • Identity assertion to the downstream server
  • Additional Application Programming Interfaces (APIs)
  • Configure Common Secure Interoperability v2 (CSIV2) inbound and outbound communication settings

    Service Data Objects, WorkManager, and Timers

    Common J specification for work and timer managers