There are two ways to customize contexts: using external definitions and using code. During the analysis and design phases of creating an application, you determine which contexts the application will use, which ones you should define externally and which ones you should create using code, and which contexts different processes can share. Typically, you use external definitions to create general, upper-level contexts such as the system context or workstation context. For lower level contexts, you typically use code to create contexts as they are needed such as creating a customer session context when a user performs business operations on an account.
The following sections describe how to define contexts or create them using code.
Contexts are externalizable objects, which means that the toolkit can create them from definitions in the context, data, and type definition files stored outside of the system. You can edit these files using any ASCII editor. For more information on externalizable objects, see Externalizers. Contexts created from external definitions are static and you declare them at installation or configuration time. Using external definition files to create contexts does not preclude creating other contexts dynamically during the runtime of the application.
To define a static context, use external definitions as shown in the following example. The first definition defines the myBranch context and the second definition defines a myWorkstation context and chains it to the myBranch context. The first definition also initializes an element (branchId) of the context's keyed collection with a value.
<CSClient id="realCSClient"/> <!-- WOSA service used in the WOSA printer sample--> <WOSADevice id="printerService" logicalName="TESTSPI" deviceType="DSEWPTR" timeout="0" SPMMinVersion="1.00" SPMMaxVersion="2.00" traceLevel="1"/>
Context can refer to service. With this function, context can manage one or more UDTT services in context lifecycle. Following is the definition sample:
The context interface has the following APIs to support this function:
public void addService(Service aService, String aServiceName, String aServiceType) throws DSEInvalidRequestException; public Hashtable getServices(); public Service getService(String aServiceName) throws DSEObjectNotFoundException; public void stopServicesInChildren() throws DSEInvalidRequestException ; public void stopServices();
When you define type="root" in the context definition, this context will be created as root context automatically when the toolkit is initialized. If there is no context definition as root context, the first context created by the application will be set as the root context.
Note There can be only one root context in the toolkit.
After you enable the auto-chain function, you can chain a context to the parent context automatically if the context has the parent context name in its definition.
In the following example, if you enable the auto-chain function, the session context will be chained to its parent branchServer context automatically after creation:
By default, the auo-chain function is not enabled. There are two ways to enable it: the application can either call API or set the attribute in btt.xml.
Class ContextFactory provides the following APIs to enable auto-chain function and query the flag:
To create a context dynamically, use code similar to the following example:
Context ctxt = new com.ibm.dse.base.Context(); ctxt.setName("myContext"); ctxt.chainTo(wksContext); /* Assumes that this is the instance of the workstation context */ ctxt.setType("test"); ctxt.setKeyedCollection(aCollection); /* Assumes that this collection is defined in the data definition file */ ctxt.addService(aService,"clientsess","cs"); /* Assumes that aService is the service, "clientsess" is the alias */ /* for that service, and "cs" the service's type */
When creating instances of contexts, the context constructor automatically creates an instance of its keyed collection and services, if they are not already instantiated. To do so, the context constructor uses the constructors defined in the externalizer class variable of the DataElement or Service class.
The code in the example uses the addService method to dynamically add a service to the context. You can add any number of services to a context.
To dynamically add data to a context, use the addElement method to add a data element to the context's keyed collection.
Note While a context has a reference to only one keyed collection of data, you can add an unlimited number of data elements within that keyed collection.
If you were using external definitions to define this context, the definition would look as follows: