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 is described above, 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. Below is an example of creating
a Properties object and setting 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 information center table of contents from the path .