The Work area partition manager interface

Applications interact with the work area partition service by using the work area partition manager interface. A user can retrieve an instance of the work area partition manager interface out of naming and use the methods that are defined in the following section.

An implementation of the work area partition manager interface is bound in Java™ naming at java:comp/websphere/WorkAreaPartitionManager. This interface is responsible for creating, retrieving, and manipulating work area partitions:

package com.ibm.websphere.workarea;

import com.ibm.websphere.workarea.UserWorkArea;
import com.ibm.websphere.workarea.PartitionAlreadyExistsException;
import com.ibm.websphere.workarea.NoSuchPartitionException;
import java.util.Properties;

public interface WorkAreaPartitionManager {
	
  //Returns an instance of a work area partition for the given name, or throws an exception if the 
  //partition name doesn't exists.                                   
  public UserWorkArea getWorkAreaPartition(String partitionName) throws NoSuchPartitionException;
	
  //Returns a new instance of a work area partition (an implementation of the UserWorkArea interface) 
  //or throws an exception if the partition name already exists.  The createWorkAreaPartition should 
  //only be used within a Java EE platform client and NOT on the 
  //server.  To create a work area partition on the server, use the WebSphere administrative 
  //console.
  public UserWorkArea createWorkAreaPartition(String partitionName, Properties props) throws
     PartitionAlreadyExistsException, java.lang.IllegalAccessException;
  }
}

EJB applications can use the work area partition manager 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.

Programmatically creating a work area partition through the createWorkAreaPartition method is only available on the Java EE client. To create a work area partition on the server, use the WebSphere® administrative console as described in the Configuring work area partitions article. All partitions in a server process must be created before server startup is complete so that the work area service can register with the appropriate container collaborators. Therefore, calling the createWorkAreaPartition method in a server process after the server starts results in a java.lang.IllegalAccessException exception. The createWorkAreaPartition method can be called in a Java EE application client at any time.

Configurable Work Area Partition Properties

This section applies to the use of the createWorkAreaPartition method on the WorkAreaPartitionManager interface. As previously described, this method should only be used on a Java EE client. To create a partition on the server, please see Configuring work area partitions.

The createWorkAreaPartition method on the WorkAreaPartitionManager interface takes a java.util.Properties objects. This Properties object, and the properties it contains, is used to define the work area partition. The following example creates a Properties object and sets a property:

Attention: A more detailed example of the usage of the WorkAreaPartitionManager can be found in Example: Using the work area partition manager.

java.util.Properties props = new java.util.Properties():
props.put("maxSendSize","12345");

Acceptable key/values pairs (properties) for defining a partition are as follows:

maxSendSize - Indicates the maximum size (bytes) of a work area that can be sent on a remote call. Acceptable values are:
- "-1" = Uses the default size of 32767.
- "0" = Unlimited size, this value will not be policed which might help performance a bit depending on the number of work area an application has.
- "1" = Integer.MAX_VALUE
maxReceiveSize - Indicates the maximum size (bytes) of a work area that can be received. Acceptable values are:
- "-1" = Uses the default size of 32767.
- "0" = Unlimited size, this value will not be policed which might help performance a bit depending on the number of work area an application has.
- "1" = Integer.MAX_VALUE
Bidirectional - Indicates if work area context that is changed by a downstream process should be propagated back upstream to the originator of that context. For a more complete description of this property, refer to the Bidirectional propagation of work area context in the Work area partition service article. Acceptable values are:
- "true" = Context changes will be returned from a remote call.
- "false" = Context changes will not be returned from a remote call.
Attention: The default setting is "false."
DeferredAttributeSerialization - Indicates if the serialization of attribute should be optimized to occur exactly once per process. For a more complete description of this property, refer to the Deferred attribute serialization of work area context section in the Work area partition service article. Acceptable values are:
- "true"
  - When an attribute is set into the work area, it will not be serialized until a remote request is made.
  - If the value is unchanged by response, the serialized form will be used for subsequent requests; the live object will be retrieved via getters.
  - When requests are made during a remote request, a value is deserialized on demand exactly once. The serialized form is used for subsequent requests from this remote process on this distributed thread; subsequent requests in process for the same attribute returns the already deserialized value. There are risks with concurrency with DeferredAttributeSerialization. After serialization in a client process, updates to the attribute are no longer reflected in the work area's copy until the value is explicitly reset through the UserWorkArea interface. Changes made to a retrieved reference in a downstream process are not propagated to subsequent downstream requests (or returned on the reply as a changed value) unless explicitly reset through the UserWorkArea interface.
- "false"
  - When an attribute is set into the work area, it is immediately serialized and the bytes are stored.
  - When an attribute is retrieved from the work area, it is always deserialized from stored bytes.
Attention: The default value is "false."
EnableWebServicePropagation - Indicates if work area context must propagate on a WebService call. Acceptable values are:
- "true" = Context propagates on a WebService call.
- "false" = Context does not propagate on a WebService call.
Attention: The default value is "false."

Exceptions

The work area partition service defines the following exceptions for use with the work area partition manager interface:

PartitionAlreadyExistsException: This exception is raised by the createWorkAreaPartition method on the WorkAreaPartitionManager implementation if a user tries to create a work area partition with a partition name that already exists. Partition names must be unique.
NoSuchPartitionException: This exception is raised by the getWorkAreaPartition method on the WorkAreaPartitionManager implementation if a user requests a work area partition with a partition name that does not exist.
java.lang.IllegalAccessException: This exception is raised by the createWorkAreaPartition method on the WorkAreaPartitionManager implementation if a user tries to create a work area partition during run time on a server process. This method can only be used on a Java EE client process. In the server process, a partition must be created using the administrative console.

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