Provides for the full support of application controlled threading.
Applications using these APIs should have the commonj-twm.jar on their build path. This is the jar that contains these APIs.
A context bean is a Java object or EJB that can be executed asynchronously by a J2EE application. The bean runs 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 and other vendor specific contexts such as:
Security
Component meta data
Context Class loader
Vendor specific contexts
There are several types of context beans:
Work
This is an object which
implements the commonj.work.Work interface. This can be run in
parallel with it's caller using the WorkManager.scheduleWork method.
WorkListener
This is a listener
callback that is executed within the local JVM as a Work progresses
through execution.
TimerListener
This is a transient timer that is executed
within the local JVM. It is not persistent and not transactional. If
the JVM fails or exits then any pending Timers are lost.
A context bean can be a Java object or a stateless local session bean. If an EJB is used then a reference to the local stub for the EJB instance must be provided. This means the EJB local interface should extend one of the above interfaces. A remote interface to an EJB cannot be used as the methods on Work, TimerListener and WorkListener are not compatible with a remote methods. 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 or use the getEJBLocalObject method to get a reference to 'this'. It is not permissible to pass 'this' when inside an EJB bean to any method taking a context bean reference. This will result in an IllegalArgumentException. Only a local stub for an EJB or a Java Bean is allowable. EJBs cannot be used with remote WorkManagers. Only JavaBeans are permissable with remote WorkManagers.
These sections describe the programming model around the context beans runtime. This is very close to the normal J2EE programming model.
Every context bean method is called using an unspecified transaction. This is very similar to container-managed transactions in a normal EJB when TX_NOT_SUPPORTED is specified. If the context bean needs to make a global transaction then it should look up java:comp/UserTransaction and start one explicitly.
If the method starts its own global transaction and the context bean method didn't commit this global transaction then the global transaction is rolled back when the method returns whether it throws an exception or not.
The J2EE component meta-data of the creating component is available to the context bean when it's a simple Java object. Obviously, if the context bean is a J2EE component such as a session bean then this is the Meta data which is active when a method is called.
However, 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 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.
By default, all are made sticky. However, a customer may want context beans to inherit some of the J2EE contexts from the creating component. The following J2EE contexts can be made sticky:
Vendor specific contexts
Context class loader.
Security.
Component Meta Data.
This only is relevant when the
context bean is a simple Java object. If it's an EJB then the
EJBs meta data is what’s active.
The application server vendor may provide a vendor specific declarative mechanism for enabling/disabling contexts for an application.
A context 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 context beans implemented with local stateless session beans. There are several differences in behavior between the two choices. The following table summarizes them:
Question |
Answer for Java beans |
Answer for EJB |
---|---|---|
Remoteable |
Yes |
No |
Transactions |
java:comp/UserTransaction is available if a global transaction is required. |
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. |
Java:comp |
The Java:comp of the component that created the context bean are always available to the context bean. |
The java:comp of the creating component is ignored. The java:comp of the EJB is always used. |
When we talk about creating an context 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 work or timer runtime. The following table lists the methods that capture the J2EE context and thus create an context bean.
Method |
Description |
---|---|
WorkManager.scheduleWork |
Start a context bean on another thread. If a WorkListener is specified then the same context is used when making calls to it. |
TimerManager.schedule |
Run the context bean when the timer expires. |
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 context bean is invoked later. The J2EE context when the context 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.
© Copyright BEA Systems, Inc. and International Business Machines Corp 2003-2004. All rights reserved.
The Timer and Work Manager for Application Servers Specification is being provided by the copyright holders under the following license. By using and/or copying this work, you agree that you have read, understood and will comply with the following terms and conditions:
Permission to copy and display the Timer and Work Manager for Application Servers Specification and/or portions thereof, without modification, in any medium without fee or royalty is hereby granted, provided that you include the following on ALL copies of the Timer and Work Manager for Application Servers Specification, or portions thereof, that you make:
1. A link or URL to the Timer and Work Manager for Application Servers Specification at this location:
http://dev2dev.bea.com/technologies/commonj/index.jsp
or at this location:
http://www.ibm.com/developerworks/library/j-commonj-sdowmt/
2. The full text of this copyright notice as shown in the Timer and Work Manager for Application Servers Specification.
IBM and BEA (collectively, the “Authors”) agree to grant you a royalty-free license, under reasonable, non-discriminatory terms and conditions to patents that they deem necessary to implement the Work Manager for Application Servers Specification.
THE Timer and Work Manager for Application Servers SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SPECIFICATION AND THE IMPLEMENTATION OF ITS CONTENTS, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT OR TITLE.
THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THE Timer and Work Manager for Application Servers SPECIFICATION.
The name and trademarks of the Authors may NOT be used in any manner, including advertising or publicity pertaining to the Timer and Work Manager for Application Servers Specification or its contents without specific, written prior permission. Title to copyright in the Timer and Work Manager for Application Servers Specification will at all times remain with the Authors.
No other rights are granted by implication, estoppel or otherwise.
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.