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:
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:
- 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.