Package com.ibm.websphere.asynchbeans
Provides for the full support of application controlled threading, asynchronous
callbacks and scoped alarms and subsystem monitors.
See:
Description
Package com.ibm.websphere.asynchbeans Description
Provides for the full support of application controlled threading, asynchronous
callbacks and scoped alarms and subsystem monitors.
Required jars
Applications that use these APIs must have the asynchbeans.jar on their classpath. This
is located in the lib directory of a WAS-E 5.0 installation.
Async Beans
An asynchronous bean is a Java object or EJB that can be executed asynchronously by a J2EE
application. The bean runs asynchronously using the J2EE context of its creator. So, for example,
it can run using the J2EE security context of the creator J2EE component. It can also run with
copies of the other J2EE contexts such as:
- Internationalization
- App Profile
- Work Area
- Access Intent
- Security
There are several flavors of asynchronous bean:
- Work
This is an object which implements the com.ibm.websphere.asynchbeans.Work interface. This is run in
parallel with it's caller using the WorkManager.startWork method.
- AlarmListener.
This is an object, which implements the com.ibm.websphere.asynchbeans.AlarmListener interface. This is
called when a high speed transient alarm expires.
- Event listener.
This can implement any interface. This is a lightweight asynchronous notification mechanism for
asynchronous events within a single JVM. Its main use is envisioned to be J2EE components within a
single EAR signaling each other various application asynchronous events.
EJBs as async beans.
An Async bean can be a Java object or a stateless session bean. If an EJB is used
then the local stubs for an instance of the EJB must be provided. This means the
EJB local interface should extend one of the above interfaces. The application
should then look up the local home of this EJB, create an instance and then
supply this instance to the Async beans APIs. It is not permissible to
pass 'this' when inside an EJB bean to any Async bean API. This will result
in an IllegalArgumentException. Only a local stub for an EJB is allowable.
Only local interfaces should be used as some of the above interfaces
have method parameters that are not serializable.
Asynchronous beans programming model
These sections describe the programming model around the async beans runtime. This is very close to the
normal J2EE programming model.
Transactions
Every asynchronous bean method is called using its own local transaction. This is very similar to
container-managed transactions in a normal EJB when TX_NOT_SUPPORTED is specified. The runtime
starts a local transaction containment before invoking the method. If the async bean needs
to make a global transaction then there are several choices:
- If the async bean was created by a servlet then it can use the UserTransaction object in
JNDI at "java:comp/UserTransaction" to do this or it can use a helper EJB method.
- If the async bean was created by an EJB then it cannot use java:comp/UserTransaction
even if the owner EJB was bean managed. It must also use a helper session or
entity bean in this case. The work to be performed inside the transaction is contained in the helper EJB method.
- If the async bean is actually an EJB then the normal J2EE transaction rules apply.
Here we have a stateless session bean whose local interface implements an async bean interface
such as Work, EventSourceEvents or AlarmListener. When this is invoked then the normal J2EE rules
apply. The TX settings that apply to the method or EJB apply. This is the most flexible way to deal
with transactions with async beans.
If the method throws an exception then any local transactions are rolled back. If the method then
returns normally, any incomplete local transactions are completed. If the method starts its
own global transaction and the async method didn't commit this global transaction then the global
transaction is rolled back when the method returns.
Access to J2EE component Meta data
The J2EE component meta-data of the creating component is available to the async bean when
it's a simple Java object. Obviously, if the asynchronous bean is a J2EE component such as a
session bean then this is the Meta data which is active when a method is called.
How-ever, when the object is a simple Java object then it is allowed to lookup the java:comp name space
like it's creator would. This allows it to lookup connection factories and EJBs in the normal J2EE way. The
environment properties of the creating component are also available. The java:comp name space is actually
identical to the one available to the creating component. All connection factories use the same resource
sharing scope as the creating component also. The only exception to this rule is that 'java:comp/UserTransaction'
is only available to the async bean when the J2EE component that created it was a servlet. It is not
visible when the owner was an EJB even if it was using bean managed transactions.
Connection Management
The method is free to use the java:comp resource-refs declared by it's creating J2EE component and
use those connections. However, it must do this using a get/use/close pattern. No connection
caching between method calls on the async bean. The connection factories them-selves can be cached
but the connections must be gotten on every method call, used and then closed.
The method can lookup connection factories using a global JNDI name but this isn't recommended as
the name is hard coded in to the application in an unnatural way (i.e. A property or worse still, a
string literal) and secondly, there is no way to specify a sharing scope for such connection factories.
Example of an async bean that uses connections correctly.
class GoodAsyncBean
{
DataSource ds;
public GoodAsyncBean()
throws NamingException
{
// ok to cache a connection factory or datasource as class instance
// data.
InitialContext ic = new InitialContext();
// we're assuming the creating J2EE component has this resource reference
// defined in it's descriptor.
ds = (DataSource)ic.lookup("java:comp/env/jdbc/myDataSource");
}
// Now when the asynch method is called, get a connection, use it and then
// close it.
void anEventListener()
{
Connection c = null;
try
{
c = ds.getConnection();
// use the connection now...
}
finally
{
if(c != null) c.close();
}
}
}
Example of a async bean that uses connections illegally
class BadAsyncBean
{
DataSource ds;
// don't do this, you can't cache connections across asynch method calls.
Connection c;
public BadAsyncBean()
throws NamingException
{
// ok to cache a connection factory or datasource as class instance
// data.
InitialContext ic = new InitialContext();
ds = (DataSource)ic.lookup("java:comp/env/jdbc/myDataSource");
// here, you broke the rules...
c = ds.getConnection();
}
// Now when the asynch method is called, illegally use the cached connection
// and you'll likely see a bunch of J2C related exceptions at runtime.
// close it.
void someAsynchMethod()
{
// use the connection now...
}
}
'Sticky' J2EE contexts and the WorkManager
We want asynchronous beans to inherit some of the J2EE contexts from the creating component. The
following J2EE contexts can be made sticky:
- Internationalization
- WorkArea
- Application Profile
- Security.
The asynchronous bean can be run as anonymous or as the client authenticated on the thread which
created it. This is useful as the asynchronous bean can only do what the caller could do; this is more
useful than the RUN_AS mechanism which prevents this sort of behavior.
- Component Meta Data.
This only is relevant when the asynchronous bean is a simple Java object. If it's an EJB then the
EJBs meta data is what's active.
The WorkManager used in conjunction with the application creating the asynchronous bean determines which contexts are sticky. There is a policy defined on the WorkManager that allows an administrator to specify the policy
Async Beans: Simple Java objects or EJBs.
An async bean can be either a Java object or a full blown EJB. Applications that are comfortable with the servlet only approach may find the Java object approach to be most desirable. Applications more comfortable with EJBs may elect to use async beans implemented with stateless session beans or entity beans.
There are several differences in behavior between the two choices. The following table summarizes them:
Question | Answer for Java beans | Answer for EJB |
Transactions | If created by a servlet then java:comp/UserTransaction is available. If created by an EJB then only TX_NOT_SUPPORTED is allowed and a 'buddy' EJB must be used for full global transaction support. | The support is what is specified by the descriptor for the EJB and the J2EE specification. |
Security | The credentials on the thread that created the async bean are used when the bean is invoked. | The credentials on the thread that created the async bean are used, however, the descriptor for the bean can override this with the run as role attribute. |
Application Profiles | The profiles active for the creating component are used. | The profiles active for the creating component are used but they may be augmented by specifying additional ones on the target EJB method. |
Java:comp | The Java:comp of the component that created the async bean are always available to the async bean. | The java:comp of the creating component is ignored. The java:comp of the async EJB is always used. |
There isn't much difference from a performance point of view. The performance is roughly equivalent to a local
method call in both cases. An EJB based async bean is basically more independent of the creating component.
When is the J2EE context remembered
When we talk about creating an async bean, this doesn't mean when we 'new'ed the actual Java object or
EJB that we want to use an as async bean. Instead, creation is when we pass the object to the
WebSphere Async Beans runtime. The following table lists the methods that capture the J2EE context
and thus create an async bean.
Method | Description |
Work.startWork | Start an async bean on another thread. |
AlarmManager.create | Run the async bean when the alarm expires. |
EventSource.addListener | Run the async bean when a matching event is published on the EventSource. |
All of these methods remember the J2EE context when they are called by an application. It is this
J2EE context that is used when the async bean is invoked asynchronously later. The J2EE context when
the async bean was newed by the application is not important. It is only when the object is passed
to one of the above methods that the J2EE context is remembered.
- Version:
- 1.1.0