JIC Engine

Author: Timo Laitinen
Date: 2004-10-31

Contents

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.

Here is an overview of the processsing flow:

Application construction model

JIC Engine is a transformer. It takes a JIC file and a set of parameters (a Map) as input and produces a graph of Java instances as output.

Actually JIC Engine returns only a single Java object. But usually this object is a large, composite object that has references to many other objects. It is a graph of Java instances.

1.1.Initializing the system with JIC Engine

Instead of constructing an application i.e. creating a graph of Java instances, JIC Engine can also be used for initializing the Java system. This can be done by calling static methods that modify the system state somehow. The process is shown here:

System initialization model

The two-way communication with JIC Engine and the classpath refers to the system initialization. Because the primary motive is to modify the system state and not create a graph of objects, the return value null means that the process doesn't output anything.

The two processes - application construction and system initialization - are separated here for clarity. In real-life, there are no significant differences and nothing prevents a single build process from both modifying the system state and constructing an application.

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. This package is independent of the rest of the JIC Engine and could be used independently for reading any kind of reasource - text files, images,, properties files, etc.
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.JICEngine

Currently, applications should use the static method build in class org.jicengine.JICEngine 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 essentially consists of :

  1. an instance of org.jicengine.io.Resource which specifies the location of the JIC file to be processed.
  2. optionally a set of parameters, in form of a java.util.Map instance.

The method returns the resulting object to the application. JICE assumes that the application knows what kind of object to expect. The application probably casts the return object to the correct type and uses the object in some way.

Currently, this is it. In order to process a JIC file, applications need to locate the file and provide the parameters and make a build request.

The JIC Engine API is very simple. There are many aspects that it doesn't take into account:

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.JICEngine.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.JICEngine.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 also 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.