JIC Engine

Author: Timo Laitinen
Date: 2004-10-02

Contents

1. Overview
2. JIC Engine API
2. 1. Class org.jicengine.JICE
2. 2. Interface org.jicengine.Builder
3. Processing JIC files from Java code
4. Command-line interface
5. JIC Engine and classpath

1. Overview

JIC Engine is a Java API for processing JIC files. It reads the XML file, interprets the configuration information of the elements and uses Java reflection API for initializing the necessary Java instances.

This image gives an overview of the processsing flow:

JICE Process

JIC Engine is a transformer. The inputs are a JIC file, a set of parameters (named Java objects) and the output is a graph of Java instances.

2. JIC Engine API

package purpose
org.jicengine The public interface to JIC Engine. Applications should use these classes for processing JIC files
org.jicengine.io General API for reading resources - e.g. JIC files. Used by JIC Engine. In principle, the classes in this package could be used outside JICE.
org.jicengine.tools Package for JICE-related tools that could help the use of JICE but are not obligatory. Contains currently only a small application for evaluating JICE.
org.jicengine.* Other subpackages are internal to JICE. Applications shouldn't use them because they are likely to change in future versions of JICE.

2. 1. Class org.jicengine.JICE

Currently, applications should use the static method build in class org.jicengine.JICE for processing a JIC file:

public static java.lang.Object build(Instructions instructions) throws Exception

The method has a few other alternatives for convenience. The Instructions instance holds the location of the JIC file to be processed and the parameters used in the build process.

2. 2. Interface org.jicengine.Builder

Don't use the org.jicengine.Builder interface yet.

The interface org.jicengine.Builder is analoguous to a javax.xml.transform.Transformer. If applications would need to interact with a Builder before processing a JIC file - like set its properties - the applications could use the method org.jicengine.JICE.getBuilder() for obtaining a Builder instance, initialize it and use it for processing the file. However, the builder doesn't currently have any methods for initializing it, so there is no need for this.

3. Processing JIC files from Java code

Any application that uses JICE must contain the code for processing the JIC file or files. Here is a simple example of how to invoke the JIC Engine in the application:

import java.util.*;

...

// locate the jic file
String filePath = "/jic-files/example1.jic";
org.jicengine.io.Resource jicFile = new org.jicengine.io.FileResource(new java.io.File(filePath));

// define the build parameters
Map parameters = new HashMap();
parameters.put("language", "en");

try {

  // process the file
  Object result = org.jicengine.JICE.build(jicFile, parameters);

  // do something with the result..

} catch (Exception e){
  // handle the exception..
}

The JICE API supports a few alternative ways for doing this but the basic process remains the same.

4. Command-line interface

Instead of invoking the JIC Engine from the Java code, JIC Engine can be started from the command-line. However, in the command-line approach you have no access to the resulting Java instance. Command-line interface can still be useful in situations where you are not interested in the resulting Java instance:

The format of the command-line interface is:

java -jar org.jicengine-1.0.jar -jic file-path [-param name value] [-param name value]

An example:

java -jar org.jicengine-1.0.jar -jic test/example1.jic -param language en -param country UK

5. JIC Engine and classpath

JIC Engine uses its classloader for instantiating and manipulating the Java objects described in the JIC file. Therefore, all application specific classes that are to be instantiated must be in the same classpath used for starting JIC Engine.

If JIC Engine is started from Java code, this is usually no problem - the application classpath contains its own classes.

If JIC Engine is started from the command-line, you must add the application classes to the Java classpath.