JIC Engine

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:

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:

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

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:

• JICE doesn't specify how the files are located.
• JICE doesn't know where the parameters are coming from. They could be hardcoded into the application code, they could be parameters passed to a servlet or they could be the output of another JIC file.
• The application has to decide when to process the JIC file.
• The application determines what to do with the resulting object.

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:

• If the JIC file would initialize a Swing application, you don't need programmatic access to the top-most JFrame instance - you probably just want to use the application that appears to the screen.
• If you want to test whether the JIC file is correct, it may be enought to just see whether the build process succeeds or fails.

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.