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 2 platform, Enterprise Edition (J2EE) 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 2 platform, Enterprise Edition (J2EE) client. To create a work
area partition on the server, use the WebSphere administrative console as
described in Configuring work area partitions.
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 J2EE 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 is described above, this method should only be used on a Java
2 platform, Enterprise Edition (J2EE) 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. Below is an example of creating a Properties
object and setting a property:
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, please
see the section "Bidirectional propagation of work area context" at Work area partition service. Acceptable values
are:
- "true" = Context changes will be returned from a remote call.
- "false" = Context changes will not be returned from a remote call.
Note: 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, please see the section "Deferred
attribute serialization of work area context" at Work area partition service.
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 arel 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.
Note: 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.
Note: 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 J2EE 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 API documentation. The generated
API documentation is available in the information center table of contents
from the path Reference > APIs - Application Programming
Interfaces.