JIC Language User Guide

1.  What Is JIC Language?

JIC Language is an XML vocabulary for defining graphs of Java objects. It provides a descriptive and specialized format for describing the state of a group of Java objects.

XML code written in JIC Language is processed by the JIC Engine, a Java program that interprets the information and creates and initializes the actual Java objects.

Before going into the details of the language, the term initialization is explained more thoroughly.

1.1. Initialization of Java Objects

The term initialization is a process where the state of a Java object is set so that it is ready to be used in an application. Although the object state may change also during its lifetime, every object has some kind of an initialization phase.

The simplest way to initialize an object is to make a constructor call. Necessary parameters are provided via constructor arguments and the object is ready for service after the instantiation. According to good object-oriented principles, an object should we in a valid state after the constructor call.

Single constuctor call is rarely enough, though. In practice the object often needs to be configured further by calling one or more of its methods. In addition, objects may also be retrieved from various factories, and the actual constructor call is hidden. And since objects have dependencies to other objects, the initialization of one Java object requires the initalization of also other objects.

The initialization of a Java object therefore consists of the following steps:

1. Collateral initialization - the initialization of additional objects:
   1. Argument objects - objects that will be used as arguments to a constructor or method call in the object acquisition phase.
   2. Helper objects - objects that are used in the initialization of the object and discarded afterwards.
2. Object acquisition - obtaining the instance to be initialized:
   1. Instantiating the object with a constructor call.
   2. Invoking a method that yields the object. (call to a factory method, for example)
   3. (Obtaining the value of a static field.)
3. State refinement - calling various initialization methods of the object.
   • Initialization methods have always side-effects and they usually do not return anything.
   • For example: setting bean properties.

Some notes:

• The initialization process is recursive - the initialization of one object may require the initialization of other objects.
• There is no single way for object acquisition - both constructor and method invocations are used.
• Full initialization requires also calling various initialization methods after the object has been acquired.

The purpose of the initialization process is to set the parameters of an object. Objects are parameterized because the values of some variables was not known when the code was written. Therefore the purpose of the initialization process is to define the detailed values for the parameters.

Details are usually information that needs to be changed relatively easily. Therefore various configuration files are used for storing the detailed values - configuration files are easier/faster to change than Java code. Example of this is the use of properties files in Java applications.

After the initialization, the object is ready to be used somehow. Usually a reference to the object is given to other objects in the application and the objects start to interact with each other via method calls. The state of the initialized object may change during its lifetime. Sooner or later the object is discarded or the whole application is stopped. The events that occur after the initialization are not in focus here. Regardless of what happens when the object is used, each object has some kind of an initialization phase.

1.2. Purpose of JIC Language

JICE is a tool specialized into the initialization and JIC Language is the XML-based language used for describing the details of the process. JIC Language code can be understood as procedural code. The JIC Engine processes the XML elements much in the order that they appear, so the elements can be thought to be executed. The XML code can be seen as a large patch process that constructs the graph of objects.

The language supports the initialization process presented in the previous chapter fully. JIC Language can be used for both defining a String and a complex graph of Swing components. No restrictions are placed on the kind of constructors or methods an object has or what interfaces it implements. JIC Language may initialize any kind of Java object.

However, JIC Language may be used only for describing the object state. It is not a general purpose programming language and can not be used for expressing complex logic. Application logic must be put into the Java classes.

Here are some of the advantages of JIC Language over plain-old Java code:

• Easier/faster to change: no compilation required.
• The XML code can be produced/manipulated dynamically with various XML technologies. (also during application lifetime.)
• The XML format is a more descriptive format for representing minor details such as numbers, texts, colors, fonts, etc.
• The XML tree visualizes the structure of the object graph better than Java code.

2.  About This Document

This document specifies the syntax and semantics of JIC Language, the XML configuration format of JICE. The document serves both as a tutorial for learning JIC Language and as the specification of the language.

In contrast, the other parts of JICE (i.e. the JIC Engine) and the way JICE could be utilized in real-life applications are not discussed.

2.1. About the Examples

All the examples are manipulating the standard J2SE classes, because the standard Java API is familiar to all Java developers.

However, JIC Language is by no means limited to operating only with the standard Java API. In fact, if JIC Language would be used in a real-life application, the JIC files would manipulate most likely the application classes.

Because the purpose of the examples is to demonstrate the capabilities of the JIC Language, some of them may seem even absurd if viewed as actual configuration files.

3.  Overview of JIC Language Syntax

Here is a list of the most significant characteristics of the JIC Language syntax:

• JIC files are XML files containing JIC Language code. The use of file-suffix .jic is encouraged.
• JIC Language specifies a common element type called JIC Element. Every XML element in a JIC File is a JIC Element.
• JIC Language does not have a fixed set of XML elements:
  • (In most cases) the author of the file chooses the name of the elements in the same way as a programmer chooses variable names.
  • In some situations the name depends on the Java API being manipulated.
  • The result is that the element names in a JIC File are always related to the domain of the application being configured.
  • Because the element names are not fixed, an exact DTD/schema of the JIC Language can not be defined.
• Every element in a JIC File must belong to the namespace http://www.jicengine.org/jic/2.1.
• JIC Language specifies a fixed set of JIC attributes. The attributes define the behaviour and semantics of an element. The attributes are:
  • action
  • args
  • class
  • if
  • instance
  • overridable-by
  • type
  • vars
• Actual values such as strings, numbers and booleans are always placed on the CDATA sections of the elements.
• Attributes are used for describing Java-specific things: constructor and method calls, classes, etc.
• Mixed content (elements inside a CDATA section) are not allowed.
• Elements may contain additional attributes, if the attributes belong to a namespace of their own. They can be used for example to store meta-data that makes it easier to manipulate the files with XML tools. The JIC Engine ignores these extra attributes when processing a JIC file.

The syntax adheres to good XML design principles. Elements define the structure of the data, CDATA is used for specifying the data and the attributes are used for meta-data. The format is very verbose - if descriptive element names are used, every string and number has a name that tells something about the meaning of the value. The names of the XML element are always related to the context of the objects being initialized.

String message = "Hello World!";
return message;

int year = 2004;
int month = 9;
int day = 9;
java.util.GregorianCalendar calendar = new java.util.GregorianCalendar(year,month,day);

calendar.setLenient(true);
calendar.setTimeZone(java.util.TimeZone.getTimeZone("GMT"));

return calendar;

4.  JIC Elements

4.1. What Are JIC Elements?

JIC Elements are the basic building blocks in JIC Language. JIC Element is an executable unit that performs individual initialization tasks. A JIC Element is capable of:

1. initializing a Java object (called element instance)
2. calling an initialization method (called action)
3. doing both of the above

In the XML file the JIC Elements appear as XML elements - every XML element in a JIC File is a JIC Element.

JIC Elements take advantage of other JIC Elements in performing complex tasks. For example, the initialization of a Java object may be a complex process - the constructor arguments must also be initialized and after construction there may be some initialization methods that must be called. In such cases the initialization is divided into simpler subprocesses that are delegated to other JIC Elements. Complex tasks are therefore executed with the help of many JIC Elements.

The cooperation/delegation relationships of JIC Elements appear as parent-child relationships of the XML elements. A JIC Element uses its child elements in achieving a complex task, and the task of an element is part of a larger task executed by the parent of the element. JIC Elements use their child elements and serve their parent elements.

4.2. Name of a JIC Element

Every JIC Element has a name that is defined by the name of the XML element:

• The name resembles a variable name
• The author of the file may choose the name in the same way a programmer may choose the name of a variable.
• Descriptive names should be used. The guidelines for choosing variable names can be applied.
• (In most cases) the name is used by the parent JIC Element for referring to the element instance of the element (more about this later).
• (In most cases) the name must be a valid Java variable name (variableName instead of variable-name or variable.name)

Note that the name is used only for identifying the element, it does not define the behaviour of the element (attributes are used for this).

4.3. Element Instance

The object initialized by a JIC Element is referred to as element instance. The attribute instance is used for specifying the instance. The value of the attribute is a simple Java expression - for example a constructor or a method call - that, when executed, will return the object.

This Java expression is referred to as the constructor of a JIC Element. When a Java object is initialized, the object acquisition step is performed by executing the constructor.

The instance attribute provides a flexible way for defining how the element instance is obtained. The kind of Java expressions supported are listed on the table below.

(The expression may contain variables that are available in the current context. The contex and the variables are explained more thoroughly later. Most often the variables refer to element instances of the child elements, so there is a child element whose name matches the variable.)

The class of the element instance must always* be defined. This is done with the attribute class that holds a full class name. The class-information is useful in situations where the class of the instance can not be directly seen from the instance attribute. The element instance of the element may also be derived from the class attribute, if the instance attribute is not specified.

*) the class attribute may be omitted in simple elements that contain CDATA. In such cases the class is either String or a primitive such as int, double or boolean.

java.util.Date date = new java.util.Date();
java.util.Calendar calendar = java.util.Calendar.getInstance();
String string_ = "This is a String";
int number = java.lang.Integer.parseInt("123");

String language = "fi";
String country = "FI";
java.util.Locale locale = new java.util.Locale(language,country);

4.4. Action

A JIC Element may also have an action. Action is a Java operation similar to the constructorr that defines the element instance. The action is also executed when the element is processed. However, the return value of action is discarded.

Action is used for calling an initialization method which have side-effects and which do not usually return anything. Actions are therefore utilized in the state refinement. However, actions do not usually call a method of their own element instance. Instead, they often modify the state of the element instance of their parent elements. After the parent element has obtained its element instance, it delivers the instance to child elements, which may modify the state of the instance.

4.5. Variable Elements And Action Elements

Element instance and action are optional - a JIC Element must have either one, or both. The action has a crucial effect on the role of a JIC Element. The purpose of elements with action is to execute the action. Elements that only define an element instance however form a variable that is used by their parent elements.

Elements with action are called action elements and elements without action are called variable elements. The situation is summarized in the following table.

Variable elements and action elements differ in the way that they cooperate with their parent elements:

1. A variable element:
   • Forms a variable:
     • the name is the name of the JIC Element
     • the value is the element instance.
   • The parent element must use the variable for something. For example:
     • the variable is used in creating the element instance.
     • the variable is used in the action.
     • the variable is used to define an element variable inside the parent element.
   • The element name must be a valid Java variable name so that it can be used in Java expressions.
2. An action element:
   • Executes an operation.
   • Typically used for:
     • Calling of a method of the element instance of the parent, e.g. setting the value of a property.
     • Calling a static method.
   • The element name has no importance.
   • The element instance of an action element can not be referenced outside the element.

4.6. Variables And Contexts

4.6.1. What Are Variables And Contexts?

Variables are objects that can be referenced by name. They are used in the Java operations of attributes instance and action.

Most variables are defined by the variable elements. In addition, the JIC Language defines a few built-in variables such as this, cdata and parent, for example.

A context is a namespace that holds a set of variables. The context defines a scope where the variable can be used. A variable must always be bound to a single context. However, because the contexts are nested, a variable may be available in many contexts regardless of this.

Every JIC Element has 3 different contexts:

• element context: for variables that are available everywhere inside the element:
  • [the element context of the parent element]
  • + those child variable elements that are marked as element variables with the attribute vars.
• instance context: for variables that are available in the instance attribute:
  • [the element context of the element]
  • + those child variable elements that are used in the instance attribute.
  • + built-in variable cdata
  • + built-in variable parent
• action context: for variables that are used in the action:
  • [the element context of the element]
  • + those child variable elements that are used in the action attribute.
  • + built-in variable this
  • + built-in variable parent

There is also a special root context. The root element of the JIC File has no parent element, but the root context can be thought of as "the element context of the parent of the root element".

The use of variables in the instance and action attribute is pretty straight-forward. A variable in the Java expression refers most often to a child element, as already shown in many examples.

4.6.2. How to Resolve the Context of a Variable?

The context of the built-in variables is predetermined. The context of variables that are defined by variable elements is always chosen by the parent element. The method is simple: the parent simply checks whether the variable is used in the attribute instance, action or vars.

4.6.3. Built-in Variables

JIC Language specifies the names of a few built-in variables:

*) the JIC Elements are processed in the order that they appear in the JIC File. The Java operation yielding the element instance is executed as soon as all the necessary variable elements have been processed, but not before. Therefore the variable parent is available only in child elements that appear after the variable elements used in the instance attribute.

4.6.4. Loose Variable Elements

If the parent can not determine a context for a variable, the variable element that defined it becomes a loose variable element. They are a kind of wildcards that are used for various purposes. By default, a loose variable element is used for setting a bean property: the name of the element defines the property name, and the element instance is the value of the property.

4.7. How JIC Elements Are Executed?

After the JIC Engine has parsed a JIC File, it starts executing the JIC elements. There is only a single root element, which is executed first.

The execution propagates to child elements - the child elements are executed as part of the execution of the parent.

The elements are always executed in the same order that they appear in the JIC file. If one wants to follow the execution by looking at the XML code, each element can be thought to be fully executed after its end tag.

The execution has the following steps:

NOTE: the execution of a JIC Element may be altered if:

4.8. Order of Child Elements

Because the order of the elements has significance, it is recommended that the child elements would always be put in a following order:

1. variable elements that are declared as element variables
2. variable elements used in the instance attribute
3. action elements and loose variable elements
4. variable elements used in the action attribute

JIC Language does not force this order but the scheme would prohibit most stupid errors like calling an initialization method before the object has been created, etc.

4.9. Summary

A JIC Element is an executable unit capable of initializing a Java object or executing a Java operation. The initialized object is referred to as element instance and the Java operation action. These two capabilities make it possible to initialize all kinds of Java objects.

JIC Elements accomplish complex initialization tasks by working together. Contexts are used for passing necessary object references from element to another.

5.  How To Define Element Instances?

This section shows in more detail how the element instance of an element can be defined.

5.1. Primitives

Internally JICE handles every primitive as a corresponding wrapper object - int is handled as an instance of java.lang.Integer, etc. The wrapper objects are converted to primitives when needed i.e. when they are used in method calls.

Therefore there is no real difference between primitives and the corresponding wrapper objects. You may use either the primitive type or the wrapper object class in the class attribute.

5.2. Using CDATA to Define Strings

Elements may access their CDATA via the variable cdata that contains the String-value of the CDATA section. The CDATA section makes it possible to define a new String, which may then be converted to other kinds of Java objects.

5.3. CDATA Conversions

Although Strings are common in configuration files, also many other kind of value objets are needed, such as numbers (int, double, etc.), booleans, urls, locales, colors, fonts, etc. JIC Language offers CDATA conversions to make the creation of these value objects easier.

There are two kinds of CDATA conversions:

Class-based CDATA conversions

The class attribute defines what kind of object is created from the CDATA.

Syntax-based CDATA conversions*

The value of the CDATA itself is used to resolve how the CDATA should be converted.

*) Syntax-based CDATA conversions are available only in JICE 2.1 and later.

In both cases, the instance attribute is omitted, which reduces the amount of XML code. With syntax-based CDATA conversions, also the class attribute is omitted.

CDATA Conversions make the use of CDATA more efficient. The String-value of the CDATA section is automatically converted to certain kinds of objects. The type of object to be instantiated is determined by the class attribute and the instance attribute may be omitted.

String string1 = "This is a String";
Integer number = new Integer(12345);
double number2 = 123.45;
boolean boolean_ = true;

CDATA conversions provide a convenient way to create data-objects that have an unambiguous String-form.

5.3.1. List of Available Class-based CDATA Conversions

All currently available conversions are listed in the following table.

5.3.2. Class-based CDATA Conversion Examples

java.awt.Color color = new java.awt.Color(255,255,255);

java.awt.Dimension dimension = new java.awt.Dimension(150,50);

java.awt.Font font = java.awt.Font.decode("Arial-10");

java.awt.Point point = new java.awt.Point(0,0);

java.net.URL url = new java.net.URL("http://www.google.com");

java.util.Locale locale = new java.util.Locale("en","US");

java.util.TimeZone timeZone = java.util.TimeZone.getTimeZone("GMT");

5.3.3. Syntax-based CDATA Conversions

If the class attribute is omitted, the syntax of the CDATA is examined to find out how it should be processed:

If you want to create a String "-1234", "true", etc., specify the attribute class="String". This disables the syntax-based CDATA conversion.

(NOTE: JICE 2.0.x did not support syntax-based CDATA conversions. if the class was omitted, the result was always a String.)

5.4. How to Invoke Constructors?

An object is instantiated by using the new operator to invoke the constructor. The constructor invocation can be defined in the instance attribute.

However, because object instantiation is a very common way to define the element instace, a shortcut is provided. The value of the instance attribute can be derived from the class attribute and the instance attribute can be left out. This saves the author from e.g. writing the class name twice.

In case the invoked constructor requires parameters, the necessary constructor arguments are defined with the attribute args that holds a list of arguments.

5.5. How to Obtain the Return-value of a Method Call?

The element instance may also be obtained via method call. For example, the object is retrieved from a static factory, which means that the static factory must be called. There are also many situations when an instance method needs to be called in order to obtain the object.

The attribute instance is used for defining the method call. There are no shortcuts provided. Below are a few examples.

Note that the attribute args is used only for defining the arguments of a constructor call. Arguments to a method call are defined inside the instance attribute.

String id = "Europe/Helsinki";
java.util.TimeZone timeZone = java.util.TimeZone.getTimeZone(id);

java.util.Calendar calendar = java.util.Calendar.getInstance(timeZone);

return calendar;

java.text.DateFormat dateFormat = java.text.DateFormat.getInstance();
java.util.Date date = new java.util.Date();
String formattedDate = dateFormat.format(date);

return formattedDate;

5.6. How to Obtain the Value of a Static Field?

The attribute instance may also be used for retrieving the value of a static field:

java.io.PrintStream out = java.lang.System.out;

String position = java.awt.BorderLayout.NORTH;

5.7. How to Obtain the Value of a Variable?

The element instance of an element may also simply be the value of a variable.

String innerMessage = "This is the message";
String message = innerMessage;

5.8. How to Create Arrays?

6.  How to Use Element Variables?

As mentioned earlier, every JIC Element has 3 contexts that each hold a set of variables:

• instance context
• action context
• element context

The instance context and action context are very restricted - they are accessed only from the instance and action attributes, respectively.

Variables in the element context however have a wider scope: they can be accessed everywhere inside the JIC Element. This includes:

• The action and instance attributes of the element.
• The action and instance attribute of every element inside the element.

The variables in the element context are called element variables. They can be thought of as a sort of global variables inside the element which can be used by many child elements.

The attribute vars is used to declare the element variables of an element. The attribute holds a comma-separated list of variables that identifies which child variable elements define the element variables.

java.text.SimpleDateFormat parseFormat = new java.text.SimpleDateFormat("yyyy-MM-dd");

java.util.HashMap birthdays = new java.util.HashMap();

birthdays.put("Britney Spears", parseFormat.parse("1981-12-02"));
birthdays.put("Christina Aguilera", parseFormat.parse("1980-12-18"));
birthdays.put("Shakira", parseFormat.parse("1977-02-02"));

return birthdays;

Local variables always override element variables.

java.text.SimpleDateFormat parseFormat = new java.text.SimpleDateFormat("yyyy-MM-dd");

java.util.HashMap birthdays = new java.util.HashMap();

birthdays.put("Britney Spears", parseFormat.parse("1981-12-02"));
birthdays.put("Christina Aguilera", parseFormat.parse("1980-12-18"));
birthdays.put("Shakira", parseFormat.parse("1977-02-02"));

java.text.SimpleDateFormat parseFormat2 = new java.text.SimpleDateFormat("dd.MM.yyyy");
birthdays.put("Justin Timberlake", parseFormat2.parse("31.01.1981"));

return birthdays;

7.  JIC Element Types

7.1. What Are JIC Element Types?

The type of a JIC Element is used to fine-tune the behaviour of the element. In most cases the type makes it easier to initialize a certain kind of object.

JIC Language defines 10 different JIC element types:

(Note: JIC Element types are not to be confused with the categories action elements and variable elements. A JIC Element is either an action element or a variable element depending on whether it has an action or not. The JIC Element type is defined by the attribute type.)

The advantage of JIC Element types comes from the way they treat loose variable elements: each type has a different policy that gives the loose variable elements a meaningful purpose.

In most cases the loose variable elements are used for modifying the element instance of the element. The same would be achieved by defining the action attribute of the child elements, but the JIC Element types make it possible to leave the action attribute out. Therefore they reduce the amount of code needed to specify certain things.

The types switch/1 and factory/x are special because they provide functionality that can not be implemented with basic language features.

7.2. JIC Element Types and Loose Variable Elements

The following table lists the policies that different JIC Element types use for loose variable elements.

The type of a JIC Element is set with the attribute type, which holds the name of the type. Default value of the attribute is bean.

The following sections show how the JIC Element types are used.

7.3. Type bean (the default)

The bean type makes it easier to set bean-like properties i.e. call setXXX()-methods. This is all it does - it does not by any means require that the initialized object is a pure bean or prohibit the invocation of other kinds of methods.

7.4. Type array

Arrays would be very tedious to initialize without the type array. Every array element would have to be added with the method java.lang.reflect.Array.set(Object array, int index, Object value).

Fortunately, the type array makes it quite straightforward to define an array.

7.5. Type collection

collection type makes it easier to populate a collection.

Every collection - list, set, etc. - may be defined also without the collection type, but it requires that every element must have an action that adds the element to the collection.

With collection type, the action attributs of the child elements may be omitted. Every loose child variable is added to the collection. The examples below demonstrates this.

(type collection is available in JICE 2.0.2 and later releases.)

7.6. Type list

The list type behaves like the more general collection, except that the element instance must implement the java.util.List interface.

7.7. Type map

The map type makes it easy to populate a java.util.Map in situations where the keys are Strings and valid XML element names.

map type handles every loose variable element as an entry in the map. The name of the element becomes the key (as a String) and the element instance becomes the value.

The map type is useful in only cases where the keys are appropriate. If other kinds of keys need to be used, the Map can always be created and populated manually.

7.8. Type container

The container type is useful as the type of the root element in large JIC Files. An element variable is created from every loose variable element, and the scope of the variables is the whole document. Therefore every loose variable element directly under the root element becomes sort of a "global object", which can then be referred to by other elements.

The same could be achieved without the container type, but then every element variable would have to be listed in the vars attribute.

The type container is also useful in making the XML tree in a JIC File flatter. A very deep tree is hard to read, but the file may be easier to understand if it is chopped to smaller units. The same phenomena occurs in Java code: it is considered bad if a single Java method contains lots of code. Therefore the code is devided into multiple smaller methods.

7.9. Type constant-of

The type constant-of/1 provides an alternative method for accessing constants i.e. static fields.

7.10. Type switch

7.11. Type factory

7.12. Type cdata-converter

8.  How to Use the if Atribute for Controlling the Execution of a JIC Element

8.1. Attribute if

The attribute if is used to control whether a JIC Element is executed or not.

The attribute holds a JIC expression that is evaluated before the element. In case the expression evaluates to false, the element is not executed. The result is the same as removing the element from the JIC File. If the expression evaluates to true or the if attribute is not set, the element is executed normally.

The if attribute is associated only with a single JIC Element. It resembles therefore a single if block in Java. It can not be used for constructing if-else or if-elseif-else like structures. See XXX (switch)

boolean doDebug = true;
if( doDebug ){
  String message = "JIC File executed";
  System.out.println(message);
}

return;

8.2. Uses for if

The effect of not executing a JIC Element is the same as removing the corresponding XML element (and its contents) from the JIC File.

Therefore the attribute if should only be used in elements that are not required in the execution of other elements. For example, removing an action elements does not usually cause the execution of the parent element to fail. However, removing a variable element may break the parent as one variable is missing.

The table below lists cases where if can be used.

Note that the expressions inside an unexecuted element are not evaluated. Hence the validity of the expressions is not verified completely. For example the use of non-existing methods or variables is not checked.

Expressions are always parsed, however, so the most trivial syntax errors and illegal class names will be encountered even if an element is not executed.

8.3. Expressions in the if attribute

The if attribute is evaluated before the execution of the element is started. The expression is executed in a context of its own, which consists of:

• [the element context of the parent element]
• + the variable parent

Note that none of the element instances that are inside the element can be referenced from the if attribute. Even the variable this can not be used.

Otherwise any valid JIC expression may be used in the if attribute. The return value of the expression is interpreted as follows:

Java APIs contain various methods where the return value null implies some kind of an error. This information may be utilized in the if attribute, because null is interpreted as false.

The ! operator may be used for negating the result. It works also with the "null or non-null" type of tests.

Operators such as =, <, >, && and || are currently NOT supported.

String propertyName = "example.property";
String propertyValue = "Example value";

if( System.getProperty(propertyName) != null ){
  System.setProperty(propertyName,propertyValue);
}

return;

9.  How to Use the switch Type for Choosing the Element Instance Dynamically

9.1. Type switch/1

The JIC Element type switch makes it possible to select the element instance of an element from a set by some criteria. It resembles the switch structure in Java language.

The switch type handles every loose variable element as a case. When an element of type switch is executed, one of the cases is selected and the element instance of the selected element becomes the element instance of the switch element.

The correct case is selected by comparing the names of the case elements with the switch variable. The element whose name equals with the String value of the variable is selected.

The switch type operates therefore on Strings, whereas in Java the switch structure is based on int values.

9.2. How to Define the Default Case?

A case named default specifies a default case that will be chosen if none of the other cases match.

java.text.DateFormat dateFormat;

String language = "en";
if ( << param "lang" is defined >> ){
  language = << value of param "lang" >>;
}

if (language.equals("fi")){
  dateFormat = new java.text.SimpleDateFormat("dd.MM.yyyy");
  dateFormat.setTimeZone(java.util.TimeZone.getTimeZone("Europe/Helsinki"));
}
else if (language.equals("en")){
  dateFormat = new java.text.SimpleDateFormat("MM/dd/yy");
  dateFormat.setTimeZone(java.util.TimeZone.getTimeZone("America/New_York"));
}
else {
  dateFormat = new java.text.SimpleDateFormat("yyyy-MM-dd");
  dateFormat.setTimeZone(java.util.TimeZone.getTimeZone("GMT"));
}

return dateFormat;

9.3. Limitations

The type switch is very limited in its capabilities as is also the switch structure in Java. The criteria for choosing a case is based on Strings. In addition, the String must be a valid XML element name.

If more complex logic is needed for choosing the element instance of an element, the logic must be put into a Java class or method which is then used from the JIC File.

10.  User-defined Factories

10.1. What Are User-defined Factories?

Factories are kind of functions that are defined and used in JIC Files. On JIC Element creates the factory, which may then be called by other JIC Elements.

Factories have parameters and they can return a Java object. Various JIC Elements may call a factory much like they would call a Java method.

The JIC Element type factory is used for defining a new factory. The element that defines a factory is referred to as a factory element. The element has a child element defines what the factory returns.

A factory may be called from the instance attribute with the syntax jic::factory-name(parameters).

10.2. When to Use Factories?

Factories are useful in situations where multiple similar objects need to be initialized with slightly varying properties. If the configuration of a single object requires 10 lines of JIC Language code, defining many such objects increases the size of the JIC File rapidly. A factory can define the common properties in the objects, and the code needed to configure a single object is reduced.

Note that the same could be achieved by creating a new Java method or class. But there are situations when the nature of the common properties does not belong to Java classes.

10.3. Type factory/x

Here are the characteristics of the factory type:

• The name of the factory element defines the name of the factory
• The parameters are defined in the type attribute in format: factory(class1 name1, class2 name2, ...). For example:
  • type="factory()"
  • type="factory(java.lang.String text)"
  • type="factory(java.lang.String text, int number)"
• The action of the element is preset to an operation that registers the factory when executed.
  • The action attribute may therefore not be used.
• The factory element must contain a single loose variable element that defines what the factory returns.
  • The element is not executed immediately after it has been processed - it is executed only when the factory is called.
  • The element has access to the factory parameters and also other variables that belong to the element context of the parent element.
• The factory element must not contain other elements.

10.4. How to Use Element Variables within Factories?

In addition to the factory parameters and the element instances defined inside the factory, also outer element variables may used in the factory.

The following example demonstrates this.

label.day1 = Monday
label.day2 = Tuesday
label.day3 = Wednesday
label.day4 = Thursday
label.day5 = Friday
label.day6 = Saturday
label.day7 = Sunday
	

label.day1 = Maanantai
label.day2 = Tiistai
label.day3 = Keskiviikko
label.day4 = Torstai
label.day5 = Perjantai
label.day6 = Lauantai
label.day7 = Sunnuntai
	

11.  User-defined CDATA Conversions

11.1. What Are User-defined CDATA Conversions

New class-based CDATA conversions may be defined in the JIC File. User-defined CDATA conversions are special factories that are identified by the target class instead of name and that always receive one parameter - the CDATA value of the element.

User-defined CDATA conversions are defined with the element type cdata-converter/1, which is similar to factory/x. The target class is given as a parameter for the type.

11.2. When to Use User-defined CDATA Conversions?

user-defined CDATA conversions are useful in situations where have some application-specific objects that have a clear string-form. In these cases the user-defined CDATA conversions make it easier to define instances of these classes.

11.3. The type cdata-converter/1

The type cdata-converter/1 behaves much like the type factory/x. Characteristics:

• There is only one argument: the class name of the target class.
• Registering to CDATA conversions for the same class is not allowed.
• Overriding a default CDATA conversion of the JIC Language is not allowed.
• The JIC element of type cdata-converter/1 may have only one child element, which will be the result of the conversion.
• The variable cdata refers to the CDATA to be converted.
  • if the child has its own CDATA, this CDATA will override the CDATA given as a parameter and the conversion will not work.
• The actual result of the CDATA conversion may be a subclass of the class that the conversion is registered to. So you can register a conversion for an interface and specify the actual implementation class only in the element that defines the CDATA conversion.

(Type cdata-converter is available in JICE 2.1.2 and later.)

12.  Build Parameters and Overridings

12.1. What Are Build Parameters?

A JIC File may receive build parameters. They are named Java objects that are given to the JIC engine at "runtime" i.e. when the JIC engine processes the JIC file. Build parameters can be used in the JIC File together with the Java objects initialized by the JIC elements.

A build parameter can be used in two ways:

1. The parameter can override the element instance of a JIC Element. This kind of a parameter is an optional one and the JIC Element being overridden provides the default value.
2. The parameter value can be retrieved explicitly. This kind of parameter is an obligatory parameter: the processing of the JIC File will fail if the parameter isn't present.

12.2. Overriding Element Instances: Attribute overridable-by

The element instance of any JIC Element can be declared to be overridable by a certain build parameter. This means that the element instance of the element serves as a default value. It is used if the parameter is not available. If the parameter exists, the parameter value will become the element instance of the element.

The attribute overridable-by declares that the element instance may be overridden. The value of the attribute is the name of the build parameter that is capable of overriding the instance.

Note that only elements marked overridable can be overridden with build parameters. There is no support for overriding any element in a JIC File.

12.3. Effects of Overriding

If an element is overridden, the element is will not be executed normally:

• Only variable elements that are used in the action will be executed.
  • all other inner variable elements are skipped.
  • all inner action elements are skipped.
• The element instance of the element is not created.
• The action of the element will be executed normally. If the action refers to the variable this, it will refer to the value of the overriding parameter.

12.4. How to Access Build Parameters Directly?

The value of a build parameter can be retrieved also directly. The instance attribute is used for this with a little peculiar syntax.

The prefix param:: is followed by the name of the parameter. The parameter name does not have to adhere to the restrictions of Java variable names.

13.  How to Access File Resources from JIC Files?

One way to access file resources from JIC Files is to use the Java IO API in the same way as any API is used in JIC Language. For example, a java.io.File object may be created and read easily.

However, JIC Language provides also tools for locating various file resources with paths relative to the current JIC File. The resource model in the package org.jicengine.io is used for this.

By a resource we mean any kind of data that is read through the java.io.InputStream or java.io.Reader classes. The resource could be a file resource that is read with java.io.FileInputStream or it could be web resource that is read through a java.net.URL. See the package org.jicengine.io for more details.

The org.jicengine.io package does not need to be used if the resources are located through absolute paths or urls. But if relative paths needs to be used, the package provides nice tools for this.

 dir/
  |_ subdir/
  |   |_ file2.properties
  |
  |_ example.jic
  |_ file1.properties

The org.jicengine.io package is a good tool for reading resources. If you want to only resolve the url to the resource instead of reading it, most, but not all, of the implementations of the org.jicengine.io.Resource interface support also this.

14.  How to Use Multiple JIC Files Together?

In a larger application there often rises a need to manipulate multipe JIC Files and use them modularily together. Here are a few examples of possible scenarios:

• Using one JIC File as input to another JIC file
• Extending a JIC File: One file serves as a default or template, which is extended by others.
• Generating JIC Files from other XML formats

JICE provides currently only the basic tools for processing single JIC Files.

14.1. How to Use the Output of a JIC File as Input to Another JIC file?

JIC Files can be chained together: the output of one JIC File can be used as input to another. This can be done in two ways:

• The output is delivered to the other JIC file as a build-parameter.
• The second JIC file asks the JIC Engine to parse the other JIC file and retrieves the output directly.

Both ways are explained in more detail below.

import org.jicengine.io.*;
import org.jicengine.*;
import java.io.*;

// ....

try {

	// locate the two files
	Resource file1 = new FileResource(new File("DateFormat.jic"));
	Resource file2 = new FileResource(new File("formatDate.jic"));

	// process the first file
	DateFormat dateFormat = (DateFormat) JICEngine.build(file1);

	// construct parameters for the second file
	Map buildParams = new HashMap();
	buildParams.put("dateFormat", dateFormat);

	// process the second file

	String formattedDate = (String) JICEngine.build(file2, buildParams);

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

	

14.2. Extending a JIC File

This refers to a situation where a JIC File needs to be modified slightly in order to derive a new configuration from it. There are many similar configurations, and there is a need to specify the common features in a single place, which is then extended.

Currently, two approaches can be used:

An example of the XSLT transformation is given below.

<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet 
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
  xmlns:j="http://www.jicengine.org/jic/2.1"
  xmlns="http://www.jicengine.org/jic/2.1"
  version="1.0"
  exclude-result-prefixes="j"
  >

<xsl:output method="xml" version="1.0" encoding="ISO-8859-1" omit-xml-declaration="no" indent="yes" />

<!--
===========================
override a single element
===========================
-->
<xsl:template match="j:formattedDate/j:dateFormat/j:pattern">
	<pattern>yyyy-MM-dd HH:mm:ss z</pattern>
</xsl:template> 

<!--
also other overridings could be specified here with similar templates.
-->


<!-- 
	this copies every other node to the result tree.
-->
<xsl:template match="@*|node()" priority="-100">
  <xsl:copy>
    <xsl:apply-templates select="@*|node()"/>
  </xsl:copy>
</xsl:template>

</xsl:stylesheet>

14.3. Generating JIC Files from other XML formats

JIC Language can be used in creating a mapping from any XML format to Java.

An application could for example specify a custom XML format, which is then converted to JIC Language code with XSLT and processed.

15.  JIC Attribute Definitions

15.1. action="JIC expression"

15.2. args="variable list"

15.3. class="full.class.name"

15.4. if="JIC expression"

15.5. instance="JIC expression"

15.6. overridable-by="parameterName"

15.7. type="typeIdentifier"

15.8. vars="variable list"

16.  JIC Expressions

A JIC expression may consists of the following expressions:

• variable - the name of a valid Java variable name
• method invocation
  • static: <full.class.Name>.method(<parameters>), or
  • instance: <variable>.method(<parameters>), where
  • <parameters> is a comma separated list of variables
• new operation
  • class: new <full.class.Name>(<parameters>), or
  • array: new <full.class.Name>[<size>]
• static field
  • format <full.class.Name>.<field name>
• negation
  • !<expression>, where
  • <expression> may be any other JIC Expression
• build parameter expression
  • param::<parameter name>
• factory call
  • jic::<factory name>(<parameters>)

The class names of inner classes contain the $ character. Instead of full.class.Name.InnerClass, the format full.class.Name$InnerClass must be used.