Developing applications that use work areas

About this task

Applications interact with the work area service by implementing the UserWorkArea interface. This interface, shown below, defines all of the methods used to create, manipulate, and terminate work areas.

package com.ibm.websphere.workarea;

public interface UserWorkArea {
   void begin(String name);
   void complete() throws NoWorkArea, NotOriginator;

   String getName();
   String[] retrieveAllKeys();
   void set(String key, java.io.Serializable value)
      throws NoWorkArea, NotOriginator, PropertyReadOnly;
   void set(String key, java.io.Serializable value, PropertyModeType mode)
      throws NoWorkArea, NotOriginator, PropertyReadOnly;
   java.io.Serializable get(String key);
   PropertyModeType getMode(String key);
   void remove(String key)
      throws NoWorkArea, NotOriginator, PropertyFixed;
}
Note: Enterprise JavaBeans (EJB) applications can use the UserWorkArea interface only within the implementation of methods in either the remote or local interface, or both; likewise, servlets can use the interface only within the service method of the HTTPServlet class. Use of work areas within any life cycle method of a servlet or enterprise bean is considered a deviation from the work area programming model and is not supported.
The work area service defines the following exceptions for use with the UserWorkArea interface:
NoWorkArea
Raised when a request requires an associated work area but none is present.
NotOriginator
Raised when a request attempts to manipulate the contents of an imported work area.
PropertyReadOnly
Raised when a request attempts to modify a read-only or fixed read-only property.
PropertyFixed
Raised by the remove method when the designated property has one of the fixed modes.

Procedure

  1. Access a partition by either: The following steps use the UserWorkArea partition as an example; however, you can use a user defined partition in the same way.
  2. Begin a new work area. Use the begin method to create a new work area and associate it with the calling thread. A work area is scoped to the thread that began the work area and is not accessible by multiple threads. The begin method takes a string as an argument; the string is used to name the work area. The argument must not be null, which causes the java.lang.NullPointer exception to be raised. In the following code example, the application begins a new work area with the name SimpleSampleServlet:
    public class SimpleSampleServlet {
    ...
       try {
          ...
          userWorkArea = (UserWorkArea)jndi.lookup(
             "java:comp/websphere/UserWorkArea");
       }
       ...
    
       userWorkArea.begin("SimpleSampleServlet");
       ...
    }

    The begin method is also used to create nested work areas; if a work area is associated with a thread when the begin method is called, the method creates a new work area nested within the existing work area.

    The work area service makes no use of the names associated with work areas; You can name work areas in any way that you choose. Names are not required to be unique, but the usefulness of the names for debugging is enhanced if the names are distinct and meaningful within the application. Applications can use the getName method to return the name associated with a work area by the begin method.

  3. Set properties in the work area. An application with a current work area can insert properties into the work area and retrieve the properties from the work area. The UserWorkArea interface provides two set methods for setting properties and a get method for retrieving properties. The two-argument set method inserts the property with the property mode of normal. The three-argument set method takes a property mode as the third argument. Both set methods take the key and the value as arguments. The key is a String; the value is an object of the type java.io.Serializable. None of the arguments can be null, which causes the java.lang.NullPointer exception to be raised. The SimpleSample application below uses objects of two classes, the SimpleSampleCompany class and the SimpleSampleProperty class, as values for properties. The SimpleSampleCompany class is used for the site identifier, and the SimpleSamplePriority class is used for the priority. These classes are shown in following code example:
    public class SimpleSampleServlet {
       ...
       userWorkArea.begin("SimpleSampleServlet");
    
       try {
          // Set the site-identifier (default is Main).
          userWorkArea.set("company",
             SimpleSampleCompany.Main, PropertyModeType.read_only);
    
          // Set the priority.
          userWorkArea.set("priority", SimpleSamplePriority.Silver);
       }
    
       catch (PropertyReadOnly e) {
         // The company was previously set with the read-only or
         // fixed read-only mode.
         ...
       }
    
        catch (NotOriginator e) {
         // The work area originated in another process,
         // so it can't be modified here.
         ...
       }
    
       catch (NoWorkArea e) {
          // There is no work area begun on this thread.
          ...
       }
    
       // Do application work.
       ...
    }
    

    The get method takes the key as an argument and returns a Java Serializable object as the value associated with the key. For example, to retrieve the value of the company key from the work area, the code example above uses the get method on the work area to retrieve the value.

    Setting property modes. The two-argument set method on the UserWorkArea interface takes a key and a value as arguments and inserts the property with the default property mode of normal. To set a property with a different mode, applications must use the three-argument set method, which takes a property mode as the third argument. The values used to request the property modes are as follows:
    • Normal: PropertyModeType.normal
    • Fixed normal: PropertyModeType.fixed_normal
    • Read-only: PropertyModeType.read_only
    • Fixed read-only: PropertyModeType.fixed_readonly
  4. Managing local work with a work area.
  5. Complete the work area. After an application has finished using a work area, it must complete the work area by calling the complete method on the UserWorkArea interface. This terminates the association with the calling thread and destroys the work area. If the complete method is called on a nested work area, the nested work area is terminated and the parent work area becomes the current work area. If there is no work area associated with the calling thread, a NoWorkArea exception is created. Every work area must be completed, and work areas can be completed only by the originating process. For example, if a server attempts to call the complete method on a work area that originated in a client, a NotOriginator exception is created. Work areas created in a server process are never propagated back to an invoking client process.
    Note: The work area service claims full local-remote transparency. Even if two beans happen to be deployed in the same server, and therefore the same JVM and process, a work area begun on an invocation from another is completed and the bean in which the request originated is always in the same state after any remote call.

    The following code example shows the completion of the work area created in the client application.

    public class SimpleSampleServlet {
       ...
       userWorkArea.begin("SimpleSampleServlet");
       userWorkArea.set("company",
           SimpleSampleCompany.Main, PropertyModeType.read_only);
       userWorkArea.set("priority", SimpleSamplePriority.Silver);
       ...
    
       // Do application work.
       ...
    
       // Terminate the work area.
       try {
          userWorkArea.complete();
       }
    
       catch (NoWorkArea e) {
          // There is no work area associated with this thread.
          ...
       }
    
       catch (NotOriginator e) {
          // The work area was imported into this process.
          ...
       }
      ...
    }
    

    The following code example shows the sample application completing the nested work area it created earlier in the remote invocation.

    public class SimpleSampleBeanImpl implements SessionBean {
    
        public String [] test() {
          ...
    
          // Begin a nested work area.
          userWorkArea.begin("SimpleSampleBean");
          try {
            userWorkArea.set("company",
                             SimpleSampleCompany.London_Development);
          }
          catch (NotOriginator e) {
          }
    
          SimpleSampleCompany company =
             (SimpleSampleCompany) userWorkArea.get("company");
          SimpleSamplePriority priority =
             (SimpleSamplePriority) userWorkArea.get("priority");
    
          // Complete all nested work areas before returning.
          try {
            userWorkArea.complete();
          }
          catch (NoWorkArea e) {
          }
          catch (NotOriginator e) {
          }
       }
    }
    
    

Example

In this example, the client creates a work area and inserts two properties into the work area: a site identifier and a priority. The site-identifier is set as a read-only property; the client does not allow recipients of the work area to override the site identifier. This property consists of the key company and a static instance of a SimpleSampleCompany object. The priority property consists of the key priority and a static instance of a SimpleSamplePriority object. The object types are defined as shown in the following code example

public static final class SimpleSampleCompany {
   public static final SimpleSampleCompany Main;
   public static final SimpleSampleCompany NewYork_Sales;
   public static final SimpleSampleCompany NewYork_Development;
   public static final SimpleSampleCompany London_Sales;
   public static final SimpleSampleCompany London_Development;
}

public static final class SimpleSamplePriority {
   public static final SimpleSamplePriority Platinum;
   public static final SimpleSamplePriority Gold;
   public static final SimpleSamplePriority Silver;
   public static final SimpleSamplePriority Bronze;
   public static final SimpleSamplePriority Tin;
}

The client then makes an invocation on a remote object. The work area is automatically propagated; none of the methods on the remote object take a work area argument. On the remote side, the request is first handled by the SimpleSampleBean; the bean first reads the site identifier and priority properties from the work area. The bean then intentionally attempts, and fails, both to write directly into the imported work area and to override the read-only site-identifier property.

The SimpleSampleBean successfully begins a nested work area, in which it overrides the client's priority, then calls another bean, the SimpleSampleBackendBean. The SimpleSampleBackendBean reads the properties from the work area, which contains the site identifier set in the client and priority set in the SimpleSampleBean. Finally, the SimpleSampleBean completes its nested work area, writes out a message based on the site-identifier property, and returns.

What to do next

For additional information about work area, see the com.ibm.websphere.workarea package in the API. The generated API documentation is available in the information center table of contents from the path Reference > APIs - Application Programming Interfaces.




In this information ...


IBM Redbooks, demos, education, and more

(Index)

Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience.

This feature requires Internet access.

Task topic    

Terms of Use | Feedback

Last updated: Sep 20, 2010 10:03:57 PM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=vela&product=was-nd-zos&topic=twa_develop
File name: twa_develop.html