Package com.ibm.websphere.asynchbeans


Provides for the full support of application controlled threading, asynchronous callbacks and scoped alarms and subsystem monitors.
See:
Description

Interface Summary

Interface Description
Alarm An object implementing this interface is returned when an alarm is created.
AlarmListener This interface is implemented by a Java object that will receive alarm notifications.
AlarmManager This manages a set of logical alarms.
AlarmManagerEvents These are events which can be thrown by an Alarm/AlarmManager.
AsynchScope An asynch bean is a scoping mechanism.
AsynchScopeEvents These are events which can be generated by an AsynchScope.
AsynchScopeManager This interface is used for object which manage a set of child asynch beans.
EventSource Runtime objects implement this when they are an event source Java objects can be registered with an EventSource.
EventSourceEvents This defines some generic events which can be thrown by all event sources.
SubsystemMonitor This represents a subsystem monitor.
SubsystemMonitorEvents These are the events which can be fired by a SubsystemMonitor.
SubsystemMonitorManager This manages a set of subsystem monitors.
Work This is implemented by applications when they want to run code blocks asynchronously.
WorkEvent This is sent to a WorkListener as the Work is processed by a WorkManager.
WorkEvents This interface defines the events which are published to an EventSource when a Work is executed and possibly fails.
WorkItem This is returned once a Work is accepted for dispatcher.
WorkListener This is a callback interface called to report on the dispatching of a Work.
WorkManager The WorkManager is the abstraction for dispatching and monitoring asynchronous work and is a factory for asynchronous beans.
WorkManagerEvents These are system events which can be thrown by a WorkManager.
WorkWithExecutionContext This is returned to wrap an application supplied Work implementation with a J2EE context.

Exception Summary

Exception Description
SerialDeserialException This can be thrown when a WorkWithExecutionContext is serialized or deserialized.
WorkCompletedException This exception indicates that a Work started but completed with an exception.
WorkContextException This exception is thrown when there is a problem with the J2EE context associated with a Work.
WorkException This is the base class for all Work related exceptions.
WorkRejectedException This is thrown then the work cannot be started.

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: There are several flavors of asynchronous bean:

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: 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: 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:
QuestionAnswer for Java beansAnswer for EJB
TransactionsIf 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.
SecurityThe 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 ProfilesThe 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:compThe 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.
MethodDescription
Work.startWorkStart an async bean on another thread.
AlarmManager.createRun the async bean when the alarm expires.
EventSource.addListenerRun 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