com.ibm.websphere.workarea
Interface WorkAreaPartitionManager


public interface WorkAreaPartitionManager

The WorkAreaManager interface defines the methods that allow a user to create their own WorkArea Partition and to retreive their WorkArea Partition. A Partition allows for private access to a given WorkArea within a Partition. A WorkArea Partition can be thought of in the same way as the UserWorkArea Partition and is defined by the UserWorkArea interface and API. The UserWorkArea Partition (bound in java:comp/websphere/UserWorkArea) is nothing more than a Partition that is publicly available and conforms to the same configuration for all users. A WorkArea Partition differse from the UserWorkArea Partition in a number of ways. First, the UserWorkArea Partition is publicly available, through java:comp, thus allowing multiple users on the same thread to access the context in the WorkArea. A WorkArea Partition on the other hand is created by a certain user and is only known to that user, unless of course that user makes its Partition publicly known. Second, a WorkArea Partition can be configured with a few differenct configuration parameters; namely Bidirectional propagation and DeferredAttributeSerialization. Bidirectional propagation allows a Partition to propigate its context in two directions. That is to say, changes made to a WorkArea's context by a downstream process will be propagated back upstream to the originator of that WorkArea. In contrast, the UserWorkArea Partition is configured such that changes made to a WorkArea's context by a downstream process are not propagated back upstream to the originator of that context. DeferredAttributeSerialization is an optimization configuration paramater to minimize the number of serialization and deserialization operations.

See Also:
UserWorkArea

Method Summary
 UserWorkArea createWorkAreaPartition(java.lang.String partitionName, java.util.Properties props)
          Returns a new instance of a WorkArea Partition or throws an exception if the Partition name already exists.
 UserWorkArea getWorkAreaPartition(java.lang.String partitionName)
          Returns an instance of a WorkArea Partition or throws an exception if the Partition name doesn't exists.
 

Method Detail

getWorkAreaPartition

public UserWorkArea getWorkAreaPartition(java.lang.String partitionName)
                                  throws NoSuchPartitionException
Returns an instance of a WorkArea Partition or throws an exception if the Partition name doesn't exists. To get a reference to your WorkArea Partition do the following in your code:


 import com.ibm.websphere.workarea.WorkAreaPartitionManager;
 import com.ibm.websphere.workarea.UserWorkArea;
 import com.ibm.websphere.workarea.NoSuchPartitionException;
 import javax.naming.InitialContext;
              . . .

 //The name in java naming the WorkAreaPartitionManager instance is bound to
 String jndiName = "java:comp/websphere/WorkAreaPartitionManager";

 //Variable to hold our WorkAreaPartitionManager reference
 WorkAreaPartitionManager partitionManager = null;

 //Get an instance of the WorkAreaPartitionManager implementation
 try {
     InitialContext initialContext = new InitialContext();
     partitionManager = (WorkAreaPartitionManager) initialContext.lookup(jndiName);
 } 
 catch (Exception e) {  
              . . .
 }

 //Variable used to hold the retrieved WorkArea Partition
 UserWorkArea myPartition = null;
 try{
     myPartition = partitionManager.getWorkAreaPartition("myPartitionName");
 }
 catch(NoSuchPartitionException e){  
              . . .
 }
              . . .
 

Parameters:
partitionName - The name of the partition to retrieve.
Returns:
A WorkArea Partition instance, should one exist, corresponding to the name passed in.
Throws:
NoSuchPartitionException - This exception will be thrown if a user requests a WorkArea Partition with the given name that doesn't exist.

createWorkAreaPartition

public UserWorkArea createWorkAreaPartition(java.lang.String partitionName,
                                            java.util.Properties props)
                                     throws PartitionAlreadyExistsException,
                                            java.lang.IllegalAccessException
Returns a new instance of a WorkArea Partition or throws an exception if the Partition name already exists. To create a WorkArea Partition on a J2EE client see the following example below. Please note that creating a Partition in the way listed below is only available on a J2EE client. To create a Partition on the server use the WebSphere Administrative Console. Retrieving a WorkArea Partition is performed in the same way on both client and server.


 import com.ibm.websphere.workarea.WorkAreaPartitionManager;
 import com.ibm.websphere.workarea.UserWorkArea;
 import com.ibm.websphere.workarea.PartitionAlreadyExistsException;
 import com.ibm.websphere.workarea.NoSuchPartitionException;
 import java.lang.IllegalAccessError;
 import java.util.Properties;
 import javax.naming.InitialContext;
              . . .

 //The name in java naming the WorkAreaPartitionManager instance is bound to
 String jndiName = "java:comp/websphere/WorkAreaPartitionManager";

 //Variable to hold our WorkAreaPartitionManager reference
 WorkAreaPartitionManager partitionManager = null;

 //Get an instance of the WorkAreaPartitionManager implementation
 try {
     InitialContext initialContext = new InitialContext();
     partitionManager = (WorkAreaPartitionManager) initialContext.lookup(jndiName);
 } 
 catch (Exception e) {  
              . . .
 }

 Properties props = new Properties();

  //Set the maxSendSize property to a desired level.
 props.put("maxSendSize","12345");
  //Set the maxReceiveSize property to a desired level.
 props.put("maxReceiveSize","54321");
  //Set the Bidirectional property to a desired value.
 props.put("Bidirectional","true");

 UserWorkArea myPartition = null;
 try{
     myPartition = manager.createWorkAreaPartition("myPartitionName",props);
 }
 catch (PartitionAlreadyExistsException e){
              . . .
 }
 catch (IllegalAccessException e){
              . . .
 }
              . . .
  //Use the UserWorkArea (WorkArea Partition) myPartition variable to 
  //call the set/get/etc. methods as defined in the UserWorkArea interface.  See the 
  //WorkArea API documentation on using the WorkArea service.
              . . .
 

Parameters:
partitionName - The name of the partition to create. Names must be non-null and unique.
props - A Properties object with the following properties to set:
  • "maxSendSize" - Indicates the maximum size (bytes) of a WorkArea to be sent on a remote call.
    Acceptable values are:
    • "-1" = use the default size (which is 32767)
    • "0" = unlimited size, this value will not be policed which might help performance a bit depending on the number of WorkArea an application has.
    • "1"....Integer.MAX_VALUE
  • "maxReceiveSize" - Indicates the maximum size (bytes) of WorkArea to be received.
    Acceptable values are:
    • "-1" = use the default size (which is 32767)
    • "0" = unlimited size, this value will not be policed which might help performance a bit depending on the number of WorkArea an application has.
    • "1"....Integer.MAX_VALUE
  • "Bidirectional" - Indicates if WorkArea context that is changed by a downstream process should be propagated back upstream to the originator of that context.
    Acceptable values are:
    • "true" = Set to "true" and context changes will be returned from a remote call.
    • "false" = Set to "false" and context changes will not be returned from a remote call. Default is "false".
  • "DeferredAttributeSerialization" - Indicates if the serialization of attribute should be optimized to occur exactly once per process.
    Acceptable values are:
    • "false" = -when an attribute is set into the WorkArea, it will be immediately serialized and bytes are stored. -when an attribute is retrieved from the WorkArea, it will always be deserialized from stored bytes. Default is "false".
    • "true" = -when an attribute is set into the WorkArea, 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 will be deserialized on demand exactly once. The serialized form will be used for subsequent requests from this remote process on this distributed thread; subsequent requests in process for the same attribute will return the already-deserialized value. There are risks with concurrency with DeferredAttributeSerialization. After serialization in a client process, updates to the attribute will no longer be reflected in the WorkArea's copy until the value is explicitely reset via the UserWorkArea interface. Changes made to a retrieved reference in a downstream process will not be propagated to subsequent downstream requests (or returned on the reply as a changed value) unless explicitely reset via the UserWorkArea interface.
Returns:
A non-null WorkArea instance.
Throws:
PartitionAlreadyExistsException - If the Partition name has already been used, this exception will be thrown.
java.lang.IllegalAccessException - On the server side, once the server has started a user can no longer create a Partition. A Partition can only be created during server startup. This exception will be thrown if a user attempts to create a Partition after the server has started.