An asynchronous bean is a Java object
or enterprise bean that can run asynchronously by a Java Platform,
Enterprise Edition (Java EE)
application, using the Java EE
context of the asynchronous bean creator.
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 that Java EE
has not previously addressed (that is, advanced 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:
- Internationalization context
- Application profiles, which are not supported for Java EE 1.4 applications and deprecated for Java EE 1.3 applications
- Work areas
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.
For more information on the Work interface, refer to the generated
API documentation.
- 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. For more information on the TimerListener interface,
refer to the generated API documentation.
- 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. For more information on the AlarmListener interface,
refer to the generated API documentation.
- Event listener
- An event listener can implement any interface. An event listener
is a lightweight, asynchronous notification mechanism for asynchronous
events within a single Java virtual
machine (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. For more information on the EventSource
interface, refer to the generated API documentation.
- 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.
For more information on the EventSourceEvents class, refer to the
generated API documentation.
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 Enterprise Java Beans (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 you call
an entity bean from within an asynchronous bean, for example, you
must have a global transactional context available on the current
thread. Because asynchronous bean objects start local transactional
contexts, you 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 you 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 Java Naming
and Directory Interface (JNDI) name, this is not recommended for the
following reasons:
- The JNDI name is hard coded in the application (for example, as
a property or string literal).
- The connection factories are not shared because there is no way
to specify a sharing scope.
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
Version 2 (CSIv2) identity assertion to be enabled. Identity assertion
is required when a
WorkWithExecutionContext object is deserialized
and run to Java Authentication and Authorization
Service (JAAS) subject identity credential assignment. Review the
following topics to better understand if you need to enable identity
assertion, when using a
WorkWithExecutionContext object:
- Configuring Common Secure Interoperability Version 2 and Security
Authentication Service authentication protocol
- Identity Assertion
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.