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:

• 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