![]() IntroductionOne of the foundations of distributed computing is the ability to pass information, typically in the form of arguments to remote methods, from one process to another. When application-level software is written over middleware services, many of the services rely on information beyond that passed in the application's remote calls. Such services often make use of the implicit propagation of private information in addition to the arguments passed in remote requests; the two most typical users of such a feature are security and transaction services. Security certificates or transaction contexts are passed without the knowledge or intervention of the user or application developer. The implicit propagation of such information means that application developers do not have to manually pass the information in method invocations, which makes programming less error-prone, and the services requiring the information do not have to expose it to application programmers. Information like security credentials can remain secret. The WebSphere work-area facility gives application programmers a similar facility. Applications can create a work area, insert information into it, and make remote invocations. The work area is propagated with each remote method invocation, eliminating the need to explicitly include an appropriate argument in the definition of every method. The methods on the server side can use or ignore the information in the work area as appropriate. If methods in a server receive a work area from a client and subsequently invoke other remote methods, the work area is transparently propagated with the remote requests. When the creating application is done with the work area, it terminates it. There are two prime considerations in deciding whether to pass information explicitly as an argument or implicitly by using a work area. These considerations are:
When information is sufficiently pervasive that it is easiest and most efficient to make it available everywhere, application programmers can use the work-area facility to simplify programming and maintenance of code. The argument does not need to go onto every argument list. It is much easier to put the value into a work area and propagate it automatically. This is especially true for methods that simply pass the value on but do nothing with it. Methods that make no use of the propagated information simply ignore it. Work areas can hold any kind of information, and they can hold an arbitrary number of individual pieces of data, each stored as a property. Structure of work areasThe information in a work area consists of a set of properties; a property consists of a key-value-mode triple. The key-value pair represents the information contained in the property; the key is a name by which the associated value is retrieved. The mode determines whether the property can be removed or modified. Property modesThere are four possible mode values for properties, as shown in Figure 1: Figure 1. Code example: The PropertyModeType definition public final class PropertyModeType { public static final PropertyModeType normal; public static final PropertyModeType read_only; public static final PropertyModeType fixed_normal; public static final PropertyModeType fixed_readonly; }; A property's mode determines three things:
The two read-only modes forbid changes to the information in the property; the two fixed modes forbid deletion of the property. The work-area facility does not provide methods specifically for the purpose of modifying the value of a key or the mode associated with a property. To change information in a property, applications simply rewrite the information in the property; this has the same effect as updating the information in the property. The mode of a property governs the changes that can be made. Modifying key-value pairs describes the restrictions each mode places on modifying the value and deleting the property. Changing modes describes the restrictions on changing the mode. Modifying key-value pairsEach property can have one of four modes, which determine how the property can be manipulated. There are two kinds of changes governed by the modes:
The four modes and their characteristics follow:
The two read-only modes forbid changes to the information in the property; the two fixed modes forbid deletion of the property. The mode is determined when the property is inserted into a work area. The default mode is normal, allowing modification and deletion of the property. Changing modesThe mode associated with a property can be changed only according to the restrictions of the original mode. The read-only and fixed read-only properties do not permit modification of the value or the mode. The fixed normal and fixed read-only modes do not allow the property to be deleted. This set of restrictions leads to the following permissible ways to change the mode of a property within the lifetime of a work area:
Nested work areasApplications can nest work areas. When an application creates a work area, a work-area context is associated with the creating thread. If the application thread creates another work area, the new work area is nested within the existing work area and becomes the current work area. Nested work areas allow applications to define and scope properties for specific tasks without having to make them available to all parts of the application. All properties defined in the original, enclosing work area are visible to the nested work area. The application can set additional properties within the nested work area that are not part of the enclosing work area. An application working with a nested work area does not actually see the nesting of enclosing work areas. The current work area appears as a flat set of properties that includes those from enclosing work areas. In Figure 2, the enclosing work area holds several properties and the nested work area holds additional properties. From the outermost work area, the properties set in the nested work are not visible. From the nested work area, the properties in both work areas are visible. Figure 2. Defining new properties in nested work areas Nesting can also affect the apparent settings of the properties. Properties can be deleted from or directly modified only within the work areas in which they were set, but nested work areas can also be used to temporarily override information in the property without having to modify the property. Depending on the modes associated with the properties in the enclosing work area, the modes and the values of keys in the enclosing work area can be overridden within the nested work area. The mode associated with a property when it is created determines whether nested work areas can override the property. From the perspective of a nested work area, the property modes used in enclosing work areas can be grouped as follows:
If an enclosing work area defines a property with one of the overridable modes, a nested work area can specify a new value for the key or a new mode for the property. The new value or mode becomes the value or mode seen by subsequently nested work areas. Changes to the mode are governed by the restrictions described in Changing modes. If an enclosing work area defines a property with one of the modes that cannot be overridden, no nested work area can specify a new value for the key. A nested work area can has delete properties from enclosing work areas, but the changes persist only for the duration of the nested work area. When the nested work area is completed, any properties that were added in the nested area vanish and any properties that were deleted from the nested area are restored. Figure 3 illustrates the overriding of properties from an enclosing work area. The nested work area redefines two of the properties set in the enclosing work area. The other two cannot be overridden. The nested work area also defines two new properties. From the outermost work area, the properties set or redefined in the nested work are not visible. From the nested work area, the properties in both work areas are visible, but the values seen for the redefined properties are those set in the nested work area. Figure 3. Redefining existing properties in nested work areas Distributed work areasIf a remote invocation is issued from a thread associated with a work area, a copy of the work area is automatically propagated to the target object, which can use or ignore the information in the work area as necessary. If the calling application has a nested work area associated with it, a copy of the nested work area and all its ancestors is propagated to the target. The target application can locally modify the information, as allowed by the property modes, by creating additional nested work areas; this information will be propagated to any remote objects it invokes. However, no changes made to a nested work area on a target object are propagated back to the calling object. The caller's work area is unaffected by changes made in the remote method. AdministrationThe work-area facility is administered by using the WebSphere Application Server administrative console and the thin client administrative tool. There are two administrative tasks associated with work areas:
The work-area facility can be used by clients and servers, and it must be enabled separately for each. On the server side, the use of work areas is enabled by default. To enable or disable the use of work areas for a server by using the administrative console, locate the server's configuration information and perform these steps:
On the client side, the use of work areas is also enabled by default. To enable or disable the use of work areas for a client, set the com.ibm.websphere.workarea.enabled property to TRUE or FALSE before starting the client. This can be done in several ways. For example, edit the launchClient script in the ${WAS_HOME}/bin directory and add the following to the Java invocation: -Dcom.ibm.websphere.workarea.enabled=false. Applications can set maximum sizes on each work area that can be sent and that can be accepted. By default, the maximum that is sent by a client and accepted, and possibly re-sent, by a server is 32,768 bytes. To change the size of a work area that can be handled by a server, or accepted to or in a server, locate the server's configuration information by using the administrative console and perform these steps:
To change the size of a work area than can be sent from a client, set the com.ibm.websphere.workarea.maxSendSize property to the desired number of bytes before starting the client. This can be done in several ways. For example, to set the maximum size to 10,000 bytes, edit the launchClient script in the ${WAS_HOME}/bin directory and add the following to the Java invocation: -Dcom.ibm.websphere.workarea.maxSendSize=10000. The maximum size that can be specified is determined by the maximum value expressible in the Java Integer data type, 2,147,483,647. The smallest maximum size that can be specified is 1. Using a maximum size of 1 byte effectively means that no requests associated with the work area can leave the system or enter another system. A value of 0 means that no limit is imposed. A value of -1 means that the default value is to be honored. The default value is also used if a invalid value or a malformed property is specified. Running work-area applicationsThe work-area service is available to any Java(TM) 2 Platform Enterprise Edition (J2EE) web module, enterprise-bean module, or client. To compile applications that use the work-area facility, ensure that the acwa.jar file is on the classpath. Special considerationsProgrammers who use work areas must take into consideration two concerns that can arise. The first is related to interoperability between the Enterprise JavaBeans and CORBA programming models, and the second is related to threading. Although the work-area facility can be used across the Enterprise JavaBeans and the CORBA programming models, many composed data types cannot be successfully utilitized across those boundaries. For example, if a SimpleSampleCompany instance is passed from the WebSphere environment into a CORBA environment, the CORBA application can retrieve the SimpleSampleCompany object encapsulated within a CORBA Any object from the work area, but it cannot extract the value from it. Likewise, an IDL-defined struct defined within a CORBA application and set into a work area will not be readable by an application using the UserWorkArea class. Applications can avoid this incompatibility by directly setting only primitive types, like integers and strings, as values in work areas, or by implementing complex values with structures designed to be compatible, like CORBA valuetypes. Also, CORBA Anys that contains either the tk_null or tk_void typecode can be set into the work area by using the CORBA interface, but the work-area specification cannot allow the J2EE implementation to return null on a lookup that retrieves these CORBA-set properties without incorrectly implying that there is no value set for the corresponding key. If a J2EE application tries to retrieve CORBA-set properties that are non-serializable, or contain CORBA nulls or void references, the com.ibm.websphere.workarea.IncompatibleValue exception is raised. Work areas must be used cautiously in applications that use the Java's Abstract Windowing Toolkit. The ATW implementation is multithreaded, and work areas begun on one thread are not available on another. For example, if a program begins a work area in response to an AWT event, like pressing a button, the work area may not be available to any other part of the application after the execution of the event completes. The example applicationThis document uses a simple application to illustrate the use of the work-area facility. In this example, the client creates a work area and inserts two properties into the work area: a site identifier and a priority. The site-identifier is set as a read-only property; the client does not allow recipients of the work area to override the site identifier. This property consists of the key company and a static instance of a SimpleSampleCompany object.The priority property consists of the key priority and a static instance of a SimpleSamplePriority object. The object types are defined as shown in Figure 4. Figure 4. Code example: The SimpleSampleCompany and SimpleSamplePriority classes public static final class SimpleSampleCompany { public static final SimpleSampleCompany Main; public static final SimpleSampleCompany NewYork_Sales; public static final SimpleSampleCompany NewYork_Development; public static final SimpleSampleCompany London_Sales; public static final SimpleSampleCompany London_Development; } public static final class SimpleSamplePriority { public static final SimpleSamplePriority Platinum; public static final SimpleSamplePriority Gold; public static final SimpleSamplePriority Silver; public static final SimpleSamplePriority Bronze; public static final SimpleSamplePriority Tin; } The client then makes an invocation on a remote object. The work area is automatically propagated; none of the methods on the remote object take a work-area argument. On the remote side, the request is first handled by the SimpleSampleBean; the bean first reads the site-identifier and priority properties from the work area. The bean then intentionally attempts, and fails, both to write directly into the imported work area and to override the read-only site-identifier property. The SimpleSampleBean successfully begins a nested work area, in which it overrides the client's priority, then calls another bean, the SimpleSampleBackendBean. The SimpleSampleBackendBean reads the properties from the work area, which contains the site identifier set in the client and priority set in the SimpleSampleBean. Finally, the SimpleSampleBean completes its nested work area, writes out a message based on the site-identifier property, and returns. The implementation of this application is discussed in Writing the example application. |