Package commonj.work

Provides for the full support of application controlled threading.

See:
          Description

Interface Summary
RemoteWorkItem If a Work instance is serializable and the WorkManager implementation supports Remoteable WorkManager then the Work can be sent to a remote member of the application cluster for execution.
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.
WorkItem This is returned once a Work is submitted to a WorkManager.
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 creating application short or long lived Works.
 

Exception Summary
WorkCompletedException This exception indicates that a Work started but completed with an exception.
WorkException This is the base class for all Work related exceptions.
WorkRejectedException This is thrown then the Work cannot be started.
 

Package commonj.work Description

Provides for the full support of application controlled threading.

Required jars

Applications using these APIs should have the commonj-wm.jar on their build path. This is the jar that contains these APIs.

JavaTM Beans with JavaTM 2 Enterprise Edition (J2EE) Context (context beans)

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:

There are several types of context bean:

EJBs as context beans.

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.

Context beans programming model

These sections describe the programming model around the context beans runtime. This is very close to the normal J2EE programming model.

Transactions

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.

Access to J2EE component Meta data

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.

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.

Which 'sticky' J2EE contexts are kept.

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:

The application server vendor may provide a vendor specific declarative mechanism for enabling/disabling contexts for an application.

Context Beans: Simple Java objects or EJBs.

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 is the J2EE context remembered

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 Notice

© Copyright BEA Systems, Inc. and International Business Machines Corp 2003. All rights reserved.

License

The 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 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 Work Manager for Application Servers Specification, or portions thereof, that you make:

1.  A link or URL to the 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 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 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 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 Work Manager for Application Servers Specification or its contents without specific, written prior permission. Title to copyright in the Work Manager for Application Servers Specification will at all times remain with the Authors.

No other rights are granted by implication, estoppel or otherwise.



Trademarks

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.



Copyright BEA Systems, Inc. and International Business Machines Corp 2003. All rights reserved.