Using a deployment descriptor

It is strongly recommend that you use the deployment descriptor alternative as it enables you to configure a context easily without having to write a single line of code. For more information, see Writing a deployment descriptor and How to load a deployment descriptor using the parse method.

You can initialize the default context by loading a deployment descriptor when calling the method IltSystem. There are several versions of the Init method, each with a different number of parameters.

The version with no parameter will attempt to load a default deployment parser named cpldeploy.xml by looking in the following places in this order:

The current directory
The user’s home directory
The user.home system property
The classpath

For more information, see the class IltSystem.

How to configure the default context through a deployment descriptor

if (isApplet())
        IltSystem.Init(this, "deploy.xml");
else
        IltSystem.Init("deploy.xml");

You can only call IltSystem once, when you initialize the application for the first time. Any further call to this method is discarded.

If the method IltSystem.Init has not been called before IltSystem.GetDefaultContext is called, the latter will implicitly call IltSystem.Init() (the version with no parameter) to initialize the default context. This has the following two effects, one a drawback and one a feature:

If you call an IltSystem.Init method with parameters, you must make sure that instances of classes using the default context are not created before IltSystem.Init is invoked. For example these instances should not be created during static initialization.
If you are working in an IDE, you can configure the default context by changing the default deployment descriptor at design time. Your context will then be automatically loaded when you instantiate the Beans at run time.

Writing a deployment descriptor

The deployment descriptor is defined by an XML file that describes how to initialize the contextual information and services.

Following is a basic example that shows you what a deployment descriptor file looks like. For a more detailed description of its syntax, see the class IlpDeploymentParser.

<?xml version="1.0"?>
<deployment xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation = "ilog/cpl/schema/deploy.xsd">
   <urlAccess verbose="true">
        <relativePath>data/images</relativePath>
   </urlAccess>
   <classManager>
        <file>model.xml</file>
   </classManager>
</deployment>

A deployment descriptor is delimited by the XML element <deployment> . This element can contain a number of subelements each corresponding to the contextual information and services as described in The concepts.

The elements that you can use to define your deployment descriptor in XML format can be found in the XML schema file <installdir> /data/ilog/cpl/schema/deploy.xsd.

Note

XML elements are not necessarily read in the order in which they appear in the file. For example, the <urlAccess> element will be systematically read before the <classManager> element even if it is placed after it in the deployment descriptor file. Therefore, you can arrange these subelements in any order.

In the example, the deployment descriptor is composed of two subelements:

The <urlAccess> element is read before the elements that potentially use it, that is, elements that require files to be loaded (the <classManager> , for example).
The <classManager> element includes a list of file elements that contain filenames. These files are read in the order in which they appear in the file.

How to load a deployment descriptor using the parse method

Once you have created a context, you can initialize it from an XML deployment descriptor using the parse method of IlpDeploymentParser.

The following example shows how to use this method to load a deployment descriptor:

IlpDefaultURLAccessService urlBootService = new IlpDefaultURLAccessService();
URL url = urlBootService.getFileLocation("deploy.xml");
IlpDeploymentParser parser = new IlpDeploymentParser(url);
IltDefaultContext context = new IltDefaultContext();
try {
  parser.parse(null, context);
} catch (Exception e) {
  e.printStackTrace();
}

In this code, IlpDefaultURLAccessService retrieves the URL to the deploy.xml file, then a new context is created and passed to the parse method. Note that the first parameter of the parse method is not used here.

Extending the deployment descriptor

If you want the deployment descriptor to perform specific initialization that is not part of the JViews TGO contextual information and services, you can extend its XML format with custom elements and write a handler to process these elements. Custom elements will be passed to the handler as DOM elements.

Here is a very basic example of a deployment descriptor with only one custom element:

<?xml version="1.0"?>
<deployment xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" 
xsi:noNamespaceSchemaLocation = "ilog/cpl/schema/deploy.xsd">
  <custom handlerClass="UserHandler"/>Joe Williams</custom>
</deployment>

Following is a basic handler class that sets the user name and stores it as a context property:

public class UserHandler implements IlpDeploymentParser.IlpCustomHandler {
  public UserHandler() {}
  public void handleCustomElement(Element customElement,
    IlpDefaultContext context) { 
      String name = customElement.getTextTrim();
      context.setProperty("userName",name);
  }
}

The deployment parser processes <custom> elements in the order in which they appear, after dealing with standard elements. It tries to load the Java™ class specified in the handlerClass attribute and instantiate it using the default constructor. Then it calls the method handleCustomElement.

Note that the custom handler must implement IlpDeploymentParser.IlpCustomHandler and provide a default constructor (with no parameter).

Current section

Initializing a context