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 the Example: Using the work area partition manager article.
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 Reference > APIs - Application
Programming Interfaces.