JIC Language

Author: Timo Laitinen
Date: 2004-10-02

Contents

1. Introduction
1. 1. Structure of a JIC file
1. 2. JIC elements
1. 3. JIC attributes
2. Behaviour of JIC elements
2. 1. Initializing Java instances
2. 2. Executing actions
2. 3. Example: Initializing a java.util.Calendar
3. Anatomy of a JIC element
3. 1. Element types
3. 2. JIC element as an XML element
3. 3. Order of child elements
3. 4. Example JIC elements
4. Variables in the action and constructor
4. 1. Examples
4. 1. 1. Referring to the element instances of inner value elements
4. 1. 2. Referring to the element instance of the JIC element itself
4. 1. 3. Referring to the element instance of the parent element
4. 1. 4. Referring to the CDATA section of the element
5. Execution of JIC elements
6. Constructors
6. 1. Attribute instance
6. 2. Implicit constructor
6. 2. 1. Attributes class and parameters can replace only 'new' operations
6. 2. 2. Attributes class and parameters make the markup more declarative
6. 2. 3. Attributes parameters and instance don't mix
6. 2. 4. Attribute class is also a type constraint
6. 3. CDATA constructor
6. 4. Default constructor of element type
7. Global instances
7. 1. When does a global instance become available?
7. 2. Local variables override global variables
8. Accessing build parameters and overridings
8. 1. Overriding element instances: attribute overridable-by
8. 2. Effects of overriding
8. 3. Accessing parameters directly.
9. JIC element types
9. 1. Element type object
9. 1. 1. Purpose
9. 1. 2. Additional value element handling
9. 1. 3. CDATA
9. 1. 4. Default constructor
9. 2. Element type bean
9. 2. 1. Purpose
9. 2. 2. Additional value element handling
9. 2. 3. CDATA
9. 2. 4. Default constructor
9. 3. Element type block
9. 3. 1. Purpose
9. 3. 2. Additional value element handling
9. 3. 3. CDATA
9. 3. 4. Default constructor
9. 4. Element type array
9. 4. 1. Purpose
9. 4. 2. Additional value element handling
9. 4. 3. CDATA
9. 4. 4. Default constructor
9. 5. Element type list
9. 5. 1. Purpose
9. 5. 2. Additional value element handling
9. 5. 3. CDATA
9. 5. 4. Default constructor
9. 6. Element type Map
9. 6. 1. Purpose
9. 6. 2. Additional value element handling
9. 6. 3. CDATA
9. 6. 4. Default constructor
9. 7. CData element types
10. JIC attributes
10. 1. type="typeName"
10. 2. instance="LJE expression"
10. 3. action="LJE expression"
10. 4. class="full.class.name"
10. 5. parameters="LJE parameter expression"
10. 6. id="idString"
10. 7. overridable-by="parameterName"
11. JIC Language and XML Namespaces

1. Introduction

JIC Language is an XML vocabulary for configuring Java objects. The language specifies the semantics of JIC elements and JIC attributes which encapsulate individual configuration instructions.

An XML file that contains JIC elements is a JIC file. The file is recommendended to have the file suffix .jic. The elements in a file form a configuration. A JIC file is processed by the JIC Engine which executes the instructions of the elements. The result is a Java instance - either a simple one or a complex instance graph.

Here is probably the simplest JIC file. When processed by the JIC Engine, it returns the String "Hello World!".

<?xml version="1.0" encoding="UTF-8"?>
<message xmlns="http://www.jicengine.org/jic/1.0"  instance="'Hello World!'"/>

1. 1. Structure of a JIC file

A JIC file doesn't have any well-specified internal structure. It is an XML file that contains JIC elements. Because of the rules of XML, there must be a single root element. JIC elements can contain other JIC elements as children, so the semantics of used JIC elements determine the exact structure of the file.

The element instance (introduced later) of the top-most element is returned as a result when the JIC Engine processes the file, so it is usually some kind of a main object

In larger JIC files, the element type (introduced later) of the top-most element is typically block, because that element type is not very strict in its structure. The flexibility is needed when complex Java instance graphs are built.

1. 2. JIC elements

JIC Language is an extraordinary XML vocabulary because it doesn't specify a XML element set i.e. it doesn't specify the names of the XML elements. Any XML element in a JIC file is considered a JIC element.

However, the language does specify the semantics of the elements and the available attributes. Each JIC element encapsulates individual configuration instructions. JIC Language specifies element types, but the names of the XML element are not used for signaling the element type of a JIC element.

Here is a summary of the properties of JIC elements:

The term JIC element is used when the properties common to every kind of element are discussed. The term element type is used for referring to the individual subtypes.

1. 3. JIC attributes

JIC Language specifies a set of JIC attributes that hold the details of the configuration instructions:

Name Purpose
action Specifies the action of the element.
instance Specifies the constructor of the element.
name Specifies the name of the element.
type Specifies the element type of the element.
class Specifies the class of the element instance of the element.
parameters Specifies parameters of the constructor.
id Makes the element instance into a global instance
overridable-by Makes the element instance overridable by an external parameter.

The attributes are described more thoroughly later.

2. Behaviour of JIC elements

In a JIC file, JIC elements encapsulate individual configuration instructions. When executed, each JIC element can:

  1. initialize a Java instance.
  2. execute an action.
  3. do both of the above.

The actual runtime behaviour of a JIC element depends on the kind of JIC attributes it has and the values of these JIC attributes. The behavioural alternatives listed above don't depend on the element type - a JIC element of any type has the potential to execute an action, for example.

These elementary capabilities give JIC Language its strength. They make it possible to encode the configuration of even complex object graphs (Java applications) into a readable XML format.

The JIC elements are divided into two groups depending on whether they execute actions or not:

value elements elements that initialize Java instances
action elements elements that execute actions
OR
elements that both initialize Java instances and execute actions.

Elements in these two categories differ in the way that they cooperate with their parent elements:

  1. A value element:
    • Initializes a Java instance and hands it over to its parent element
    • The parent decides how the instance is used.
    • A value element resembles a method that returns a value.
  2. An action element:
    • Executes an operation. Doesn't return anything to its parent element.
    • An action element resembles a method whose return type is void.

NOTE: don't mix these behavioural types with element types (object, block, bean, array, etc)

2. 1. Initializing Java instances

If a JIC element has a constructor , it will initialize a Java instance when executed. The Java instance that is initialized is referred to as an element instance . The initialization is considered as a process which consists of the following steps:

  1. the necessary parameters are created (or obtained).
  2. the Java instance is created (or obtained):
    1. a Java class is instantiated with the new operation.
    2. an instance is obtained from a factory.
    3. etc.
  3. the methods of the instance are called.
    • E.g. the properties of the instance are set.

A JIC element typically has other JIC elements as children that perform some parts of the process. They are executed as part of the execution of the parent element. Typically the parameters are produced by inner value elements (Step 1) and the method-calling is done by inner action elements (Step 2).

The step 2 is done by the JIC element itself. It has a constructor, a simple Java operation that creates or obtains the element instance. The constructor can be set with the attribute instance, although there are other ways for this also. The value of the attribute is a simple Java operation (a Limited Java Expression (LJE) to be precise) The variables in the expression refer to the element instances produced by the inner value elements.

2. 2. Executing actions

Action elements execute actions. It this context an action is a simple Java operation like a method call. The execution of an action may be considered to have the following steps:

  1. the necessary parameters are created (or obtained).
  2. the method is invoked.

Child elements are typically used for creating the parameters. The action is set with the attribute action, whose value is a Java expression. (actually a Limited Java Expression (LJE).) The variables in the expression refer to the element instances produced by the inner value elements.

2. 3. Example: Initializing a java.util.Calendar

Here is an example JIC file that demonstrates the initialization of a java.util.Calendar instance. A couple of the elements also execute a few actions:

<?xml version="1.0" encoding="UTF-8"?>
<calendar xmlns="http://www.jicengine.org/jic/1.0"  instance="new java.util.GregorianCalendar(year,month,date)">
  <year  instance="2004"/>
  <month  instance="9"/>
  <date  instance="9"/>
  <lenient  action="PARENT.setLenient(this)"  instance="true"/>
  <timeZone  action="PARENT.setTimeZone(this)"  instance="java.util.TimeZone.getTimeZone(id)">
    <id  instance="'GMT'"/>
  </timeZone>
</calendar>

In the example, the initialization process is executed as follows:

  1. the constructor parameters are obtained from child elements <year>, <month> and <date>
  2. <calendar> creates the java.util.GregorianCalendar instance.
  3. elements <lenient> and <timeZone> set the properties lenient and timeZone of the java.util.GregorianCalendar instance. They are only elements that perform actions.

This table summarizes the properties of the elements in the example.

element constructor
(operation)
element instance action
(operation)
behavioural type
calendar new java.util.GregorianCalendar(year, month, date) instance of java.util.GregorianCalendar - value element
year 2004 instance of java.lang.Integer - value element
month 9 instance of java.lang.Integer - value element
date 9 instance of java.lang.Integer - value element
lenient true instance of java.lang.Boolean PARENT.setLenient(this) action element
timezone java.util.TimeZone.getTimeZone(id) instance of java.util.TimeZone PARENT.setTimeZone(this) action element
id 'GMT' "GMT" (a String) - value element

The example corresponds roughly to the following Java code:

int year = 2004;
int month = 9;
int date = 9;

java.util.Calendar calendar = new java.util.GregorianCalendar(year,month,date);

boolean lenient = true;
calendar.setLenient(true);

String id = "GMT";
java.uti.TimeZone timeZone = java.util.TimeZone.getTimeZone(id);
calendar.setTimeZone(timeZone);

return calendar;

When the JIC Engine processes the file, the instance of the top-most element is returned as the result.

3. Anatomy of a JIC element

A JIC element has the following characteristics:

  1. It always has a name
  2. It might have a constructor .
  3. It might have an action .
  4. It might have an id .
  5. It might have inner JIC elements as children:
    1. inner value elements
      1. elements used as constructor parameters
      2. elements used as action parameters
      3. other elements. (called additional value elements)
    2. inner action elements

These properties are common to all JIC elements, regardless of the element type of the element. The following table lists these properties together with a short description.

Property Type Purpose Optionality
name String
(Java variable name)
If the element is a value element, the parent element uses the element name for referring to the element instance of the element.

The name should be a valid Java variable name.
Required
constructor Java operation Creates (or obtains) the element instance i.e. the Java instance initialized by the element. either one of these
action Java operation A method invocation. May set the property of the element instance of the parent. Or do something else.
id String Makes the element instance a global instance, which can be referenced by any element. (normally only the parent element can refer to the instance). The id must be unique within the same JIC file. optional.
inner value elements JIC element The element instances of the inner value elements can be used in many ways:
  1. as parameters for the constructor
  2. as parameters for the action
  3. other uses depend on the element type
the type of required/allowed elements depends on the action, constructor and element type of the element.
inner action elements JIC element Typically take part in the initialization of the element instance by setting its properties or by calling some other methods of the instance.

In principle the inner action elements could do anything. Their actions don't have to be related to the initialization of the instance. They could write a debug message to System.out, for example.
optional.

The following table tries to summarize the different properties that a JIC element might have depending on its behaviour.

Value elements Action elements
property Elements that initialize a Java instance Elements that execute an action Elements that do both
name yes yes yes
element type yes yes yes
constructor yes - yes
action rarely yes yes
id maybe. - maybe.
inner value elements
(constructor parameters)
probably.
(if the constructor uses variables)
- probably.
(if the constructor uses variables)
inner value elements
(action parameters)
- probably.
(if the action uses variables)
probably.
(if the action uses variables)
additional value elements
maybe.
(depends on the element type.)
- maybe.
(depends on the element type.)
inner action elements* maybe.
(probably for initializing the element instance created by the constructor.)
probably not maybe.
(probably for initializing the element instance created by the constructor.)

* A JIC element can almost always have an inner action element. In principle, the action elements can do anything. However, they are usually used for initializing the element instance.

3. 1. Element types

JIC Language specifies several element types, which are subclasses of the common abstract JIC element type. The currently supported element types are: object, bean, block, array, list, map, int, double, long, float, boolean, color, font and resource.

The element type of a JIC element specifies how the element will handle its additional value elements i.e. inner value elements that are not used in the action or the constructor. The element types are described in more detail in the chapter XXXX.

NOTE: element types are not to be confused with the behavioural categories action elements and value elements. A JIC element of any concrete type can be either an action element or a value element depending on whether it has an action or not.

Most of the element types exist only because they make the XML code nicer or more compact. A few of the types are obligatory - without them, JIC Language couldn't initialize any kind of Java object.

3. 2. JIC element as an XML element

In a JIC file, the JIC elements are XML elements that belong to the JIC namespace http://www.jicengine.org/jic/1.0 and that contain JIC attributes. The JIC attributes specify the properties of the elements.

The logical properties are implemented as follows:

Property XML implementation
name The local name of the XML element specifies the name.

The name can also be specified with JIC attribute name.
element type the element type is set with the attribute type. Default is bean.
constructor many ways:
  1. if present, the JIC attribute instance specifies the constructor.
  2. if present, the attributes class and parameters specify an implicit constructor.
  3. depending on the element type, the element might have a default constructor.
  4. if none of the above applies and the element contains CDATA, the CDATA-string will become element instance of the element. (a static constructor will be used that always returns the String value of the CDATA.)
action JIC attribute action specifies the action.
id set with the attribute id.
child elements Naturally, child elements are XML elements inside the parent element.

However, also CDATA content forms a special child element that has the name CDATA.

3. 3. Order of child elements

It is recommended that the child elements would be put in a following order:

  1. inner value elements that are constructor parameters.
  2. additional value elements and inner action elements. (these elements can be mixed. The best order depends on the situation.)
  3. inner value elements that are action parameters.

JIC Language doesn't force this kind of order but a common scheme would make the configuration more readable.

3. 4. Example JIC elements

Element <string> has a constructor that always returns the same String:

<string  instance="'this is a java.lang.String'"/>

The example above corresponds roughly to Java code:

Object string = "this is a java.lang.String";

Element <string2> has a constructor that refers to the element instance of a child element:

<string2  instance="value">
  <value  instance="'this is also a java.lang.String'"/>
</string2>

The example above corresponds roughly to Java code:

Object value = "this is also a java.lang.String";
Object string2 = value;

Element <string3> has a constructor that refers to the CDATA of the element:

<string3  instance="CDATA">this is also a java.lang.String</string3>

The example above corresponds roughly to Java code:

Object CDATA = "this is also a java.lang.String";
Object string3 = CDATA;

Element <string4> takes advantage of the fact that an element with CDATA and no other attributes will have the CDATA as its value:

<string4>this is also a java.lang.String</string4>

The example above corresponds roughly to Java code:

Object string4 = "this is also a java.lang.String";

Element <log> has an action that uses two variables: this refers to the element instance of the element itself and out refers to the element instance of the child <out>:

<log  action="out.println(this)"  instance="'this is a message'">
  <out  instance="java.lang.System.out"/>
</log>

The example above corresponds roughly to Java code:

Object log = "this is a message";
Object out = java.lang.System.out;

out.println(log);

Element <locale> has a constructor that refers to the element intances of the child elements:

<locale  instance="new java.util.Locale(language,country)">
  <language  instance="'fi'"/>
  <country  instance="'FI'"/>
</locale>

The example above corresponds roughly to Java code:

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

The same example could be written by using the attributes class and parameters instead of the attribute instance:

<locale  class="java.util.Locale"  parameters="language,country">
  <language  instance="'fi'"/>
  <country  instance="'FI'"/>
</locale>

Element <element> has an action that refers to the element instances of the parent element and the two child elements:

<map  instance="new java.util.HashMap()">
  <element  action="PARENT.put(key,value)">
    <key  instance="'key1'"/>
    <value  type="int">12345</value>
  </element>
</map>

The example above corresponds roughly to Java code:

Map map = new java.util.HashMap();

Object key = "key1";
Object value = new Integer(12345);

map.put(key,value);

4. Variables in the action and constructor

Action and constructor a JIC element are both Java operations. In most cases, the operations have variables that refer to objects outside the operations themselves. The variables in action and constructor can refer to:

  1. element instances of the inner value elements.
  2. the element instance of the parent element.
  3. global instances.
  4. the element instances of the element itself.

(Global instances are described in more detail in chapter XXX)

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

Name Refers to
PARENT the element instance of the parent element.
this the element instances of the element itself.
(can be used only in the action).
CDATA refers to the String-value of the elements CDATA section.
JICEContext *TODO*

Other variables are interpreted as follows:

  1. If the element has an inner value element with the same name, the variable refers to the element instance of that child element.
  2. If none of the child elements match, the variable refers to a global instance with a matching id.
  3. If there isn't a matching global instance, the variable is illegal and will result in exception when executed.

Here are a few consequences of the variable rules:

The action of an element is set with the attribute action. In these examples the constructor is set with the attribute instance, although there are other ways for doing this also.

4. 1. Examples

4. 1. 1. Referring to the element instances of inner value elements

<?xml version="1.0" encoding="UTF-8"?>
<locale xmlns="http://www.jicengine.org/jic/1.0"  instance="new java.util.Locale(language,country)">
  <language  instance="'fi'"/>
  <country  instance="'FI'"/>
</locale>

NOTE: you can refer only to instances of child elements that DO NOT have an action.

4. 1. 2. Referring to the element instance of the JIC element itself

<?xml version="1.0" encoding="UTF-8"?>
<list xmlns="http://www.jicengine.org/jic/1.0"  instance="new java.util.ArrayList()">
  <e  action="PARENT.add(this)"  instance="10"/>
  <e  action="PARENT.add(this)"  instance="12"/>
  <e  action="PARENT.add(this)"  instance="340"/>
  <e  action="PARENT.add(this)"  instance="9"/>
</list>

4. 1. 3. Referring to the element instance of the parent element

See example above.

4. 1. 4. Referring to the CDATA section of the element

<?xml version="1.0" encoding="UTF-8"?>
<message xmlns="http://www.jicengine.org/jic/1.0"  instance="CDATA">Hello World!</message>

5. Execution of JIC elements

After a JIC file has been parsed, the JIC elements are executed. There is only a single root element, which is executed first. The execution is recursive - 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.

The execution has the following steps:

  1. child elements are executed one by one, until all inner value elements needed in the constructor are processed.
  2. The constructor of the element is executed, which yields the element instance of the element.
  3. Rest of the child elements are executed, again one by one.
  4. The element instance is now fully initialized. It is made a global instance, if necessary (if the element has the id attribute).
  5. the action of the element is executed.

NOTE: the execution order above applies only if the element is not overridden.

6. Constructors

6. 1. Attribute instance

The attribute instance is the default way for specifying the constructor of an element.

6. 2. Implicit constructor

Attributes class and parameters provide an alternative for the attribute instance. The constructor defined by the two attributes is called an implicit constructor in constrast with attribute instance, which declares the constructor quite explicitly.

The use of these two attributes is best understood with examples. Here is a jic fragment where the elements <list> and <list2> are both functionally the same:

<list  instance="new java.util.ArrayList()"/>
<list2  class="java.util.ArrayList"/>

The parameters attribute is needed, if there are constructor parameters:

<list  instance="new java.util.ArrayList(20)"/>
<list2  class="java.util.ArrayList"  parameters="20"/>

The constructor new java.util.ArrayList(20) is derived automatically from the attributes class and parameters.

6. 2. 1. Attributes class and parameters can replace only 'new' operations

Most of the constructors in JIC elements will probably be new operations, like new java.util.Date() for example. However, there can be other kind of constructor operations also:

These constructors must be specified with instance attribute, which can handle all of these cases.

6. 2. 2. Attributes class and parameters make the markup more declarative

The main purpose of class and parameters attributes is to make the markup more declarative. The attributes class and parameters are shortcuts - if they cause trouble, one can always rely only on the instance attribute.

6. 2. 3. Attributes parameters and instance don't mix

The attribute parameters can not be used together with the attribute instance. Specifying them both will result in exception.

6. 2. 4. Attribute class is also a type constraint

The attribute class serves also as a type constraint. The element instance must be an instance of the class stated in the class attribute.

This second nature of the class becomes evident only when used together with the instance attribute. (specifying them both is legal, by the way). Here are a few examples:

<list  class="java.util.ArrayList"  instance="new java.util.ArrayList(20)"/>
<list2  class="java.util.List"  instance="new java.util.ArrayList(20)"/>

If the instance attribute is present, the class attribute is used only for constraining the type of the element instance. In the element <list>, the class attribute states that the element instance is an instance of java.util.ArrayList. In the element <list2>, the class attribute is not as strict, it states that the element instance is an instance of java.util.List.

This feature may be useful if the constructor fetches the element instance from a factory. The type of object returned by a factory might not always be clear, so the class makes two things:

  1. asserts that the object returned by the constructor is an instance of a certain class. If not, an exception is thrown.
  2. tells to anyone reading the JIC file what the class of the element instance is.

Consider the difference of the two elements <label> and <label2> in this JIC fragment:

<label  instance="some.application.LabelFactory.get(name)">
  <name>label_1</name>
  <background  instance="new java.awt.Color(0,0,255)"/>
</label>
<label2  class="javax.swing.JLabel"  instance="some.application.LabelFactory.get(name)">
  <name>label_2</name>
  <background  instance="new java.awt.Color(0,0,255)"/>
</label2>

The fact that the class attribute of the element <label2> tells that we are dealing with javax.swing.JLabel makes the configuration much clearer.

6. 3. CDATA constructor

TODO..

6. 4. Default constructor of element type

TODO..

7. Global instances

So far all the variables in the action and constructor have been referring to the element instances of elements that are close to the element - child elements, the parent element or the element itself.

Global instances are a sort of global variables that are visible in the whole JIC file. The only condition is that the JIC element that defined the global instances must be processed before the instance is used.

The element instace of any value element can be made global with the attribute id. Here is an example:

<?xml version="1.0" encoding="UTF-8"?>
<container xmlns="http://www.jicengine.org/jic/1.0"  type="block"  instance="formattedDate">
  <dateFormat  class="java.text.SimpleDateFormat"  parameters="pattern,locale"  id="dateFormat">
    <pattern>dd.MM.yyyy HH:mm:ss z</pattern>
    <locale  class="java.util.Locale"  parameters="language,country">
      <language>fi</language>
      <country>FI</country>
    </locale>
  </dateFormat>
  <date  class="java.util.Date"  id="timestamp"/>
  <formattedDate  instance="dateFormat.format(timestamp)"/>
</container>

The elemens <dateFormat> and <date> both have the id attribute. This declares that their element instances are global instances - they can be referred by other elements.

The element <formattedDate> uses both of the global instances in its instance attribute.

7. 1. When does a global instance become available?

A global instance is available in elements that come after the closing tag of the element that defined the global instance.

The elements in a JIC file are processed in the sequence that they appear in the file. A global instance becomes available as soon as the instance is fully initialized - which is when the JIC element that defines the instance has been fully processed.

7. 2. Local variables override global variables

If the local context of an element contains a variable with the same name than a global variable - i.e. if an element has a child element whose name equals to the id attribute of some other element - the local variable will override the global one.

In this example, the element <formattedDate> has a child element <timestamp>, and the variable timestamp in the constructor dateFormat.format(timestamp) refers to the element instance of the child. The child element overrides the global variable timestamp created by the element <date>.

<?xml version="1.0" encoding="UTF-8"?>
<container xmlns="http://www.jicengine.org/jic/1.0"  type="block"  instance="formattedDate">
  <dateFormat  class="java.text.SimpleDateFormat"  parameters="pattern,locale"  id="dateFormat">
    <pattern>dd.MM.yyyy HH:mm:ss z</pattern>
    <locale  class="java.util.Locale"  parameters="language,country">
      <language>fi</language>
      <country>FI</country>
    </locale>
  </dateFormat>
  <date  class="java.util.Date"  id="timestamp"/>
  <formattedDate  instance="dateFormat.format(timestamp)">
    <timestamp  class="java.util.Date"/>
  </formattedDate>
</container>

8. Accessing build parameters and overridings

A JIC file can receive build parameters. Parameters 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 created 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.
  2. The parameter can be accessed directly by its name.

8. 1. Overriding element instances: attribute overridable-by

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

The attribute overridable-by declares that the element instance of that element is overridable. The value of the attribute is the name of the parameter that can override the instance.

Here is a short example of overriding. The element <message> is overridable by the parameter named message.

<?xml version="1.0" encoding="UTF-8"?>
<container xmlns="http://www.jicengine.org/jic/1.0"  action="out.println(message)">
  <message  overridable-by="message">Default message</message>
  <out  instance="java.lang.System.out"/>
</container>

8. 2. Effects of overriding

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

For example, if the following JIC file is processed with the parameter message, the element <inner-action-element> will never be executed.

<?xml version="1.0" encoding="UTF-8"?>
<container xmlns="http://www.jicengine.org/jic/1.0"  action="out.println(message)">
  <message  overridable-by="message">Default message</message>
  <out  instance="java.lang.System.out"/>
</container>

8. 3. Accessing parameters directly.

TODO ***

9. JIC element types

Element types can be thought of as concrete implementations of the abstract JIC element type. The general type already specifies most of the aspects of JIC elements, so the subclasses differ from each other only in a few things.

Currently, an element type specifies:

All other aspects are common to all JIC elements

Here is a simple example of an element type. The type int makes it easier to specify an integer in the CDATA section because it provides a default constructor that parses the CDATA string into an integer.

<value  instance="java.lang.Integer.parseInt(CDATA)">123</value>
<value  type="int">123</value>

The element type is set with the attribute type. The default value of the attribute is bean. The types can be categorized as follows:

The element types are described one by one in the following chapters.

9. 1. Element type object

9. 1. 1. Purpose

object type has probably no actual use. It is the simplest one, because it doesn't provide any additional features.

9. 1. 2. Additional value element handling

A JIC element whose element type is object can't contain additional value elements.

9. 1. 3. CDATA

Can contain CDATA, if the variable CDATA is used in the action or constructor.

9. 1. 4. Default constructor

No default constructor provided.

9. 2. Element type bean

9. 2. 1. Purpose

Many Java classes have bean properties. When an object is initialized, these properties are usually set. Element type bean makes this easier.

9. 2. 2. Additional value element handling

All additional value elements are used for setting the properties of the element instance

Here is an example how the two properties lenient and timeZone of the java.util.Calendar would be set with the element type object:

<?xml version="1.0" encoding="UTF-8"?>
<calendar xmlns="http://www.jicengine.org/jic/1.0"  type="object"  instance="new java.util.GregorianCalendar()">
  <lenient  action="setLenient(this)"  instance="true"/>
  <timeZone  action="setTimeZone(this)"  instance="java.util.TimeZone.getTimeZone(id)">
    <id  instance="'GMT'"/>
  </timeZone>
</calendar>

With element type bean, the two action attributes can be removed and the configuration becomes a bit simpler:

<?xml version="1.0" encoding="UTF-8"?>
<calendar xmlns="http://www.jicengine.org/jic/1.0"  instance="new java.util.GregorianCalendar()">
  <lenient  instance="true"/>
  <timeZone  instance="java.util.TimeZone.getTimeZone(id)">
    <id  instance="'GMT'"/>
  </timeZone>
</calendar>

9. 2. 3. CDATA

Can contain CDATA. If the CDATA is not otherwise used, it will be used for setting the property CDATA.

9. 2. 4. Default constructor

No default constructor provided.

9. 3. Element type block

9. 3. 1. Purpose

When a large application is configured, the Java instances form often a graph instead of a tree. In JIC Language, the graph of objects can be created with the element type block and with global instances.

block makes it possible to put many arbitrary JIC elements inside a single JIC element. The element type of the top-level element in a JIC file is typically block

9. 3. 2. Additional value element handling

All additional value elements are allowed. Nothing special is done with them, they are just allowed to exist.

Here is an example where the top-level element has the element type block:

<?xml version="1.0" encoding="UTF-8"?>
<container xmlns="http://www.jicengine.org/jic/1.0"  type="block"  instance="dates">
  <dateFormat  class="java.text.SimpleDateFormat"  parameters="pattern"  id="parseFormat">
    <pattern>yyyy-MM-dd HH:mm:ss</pattern>
  </dateFormat>
  <dates  instance="new java.util.ArrayList()">
    <date  action="PARENT.add(this)"  instance="parseFormat.parse(CDATA)">2004-01-01 15:00:00</date>
    <date  action="PARENT.add(this)"  instance="parseFormat.parse(CDATA)">2004-02-01 15:00:00</date>
    <date  action="PARENT.add(this)"  instance="parseFormat.parse(CDATA)">2004-03-01 15:00:00</date>
  </dates>
</container>

The <dateFormat> element is used in the three <date> elements. Element type block make it possible to declare first the <dateFormat> as a global instance and then use it in the other elements.

9. 3. 3. CDATA

Can contain CDATA.

9. 3. 4. Default constructor

No default constructor provided.

9. 4. Element type array

9. 4. 1. Purpose

Makes it possible to create both object arrays and primitive arrays.

9. 4. 2. Additional value element handling

All additional value elements are used as array elements.

Here are a few examples:

<?xml version="1.0" encoding="UTF-8"?>
<array xmlns="http://www.jicengine.org/jic/1.0"  class="int[]"  type="array">
  <e  instance="1"/>
  <e  instance="2"/>
  <e  instance="3"/>
  <e  instance="4"/>
</array>
<?xml version="1.0" encoding="UTF-8"?>
<array xmlns="http://www.jicengine.org/jic/1.0"  class="java.lang.String[]"  type="array">
  <e>Element 1</e>
  <e>Element 2</e>
  <e>Element 3</e>
  <e>Element 4</e>
</array>

9. 4. 3. CDATA

Can't contain CDATA.

9. 4. 4. Default constructor

Has a custom default constructor which can't be overridden. The constructor can't be expressed as a value of the instance attribute, but it will instantiate and populate an array.

9. 5. Element type list

9. 5. 1. Purpose

Makes it easy to create and populate a java.util.List instance.

9. 5. 2. Additional value element handling

All additional value elements are used as list elements.

Without the list type, all the elements would have to be added to the list explicitly:

<?xml version="1.0" encoding="UTF-8"?>
<list xmlns="http://www.jicengine.org/jic/1.0"  instance="new java.util.ArrayList()">
  <e  action="PARENT.add(this)"  instance="1"/>
  <e  action="PARENT.add(this)"  instance="2"/>
  <e  action="PARENT.add(this)"  instance="3"/>
  <e  action="PARENT.add(this)"  instance="4"/>
</list>

With list type, the action attributes can be left out:

<?xml version="1.0" encoding="UTF-8"?>
<list xmlns="http://www.jicengine.org/jic/1.0"  class="java.util.ArrayList"  type="list">
  <e  instance="1"/>
  <e  instance="2"/>
  <e  instance="3"/>
  <e  instance="4"/>
</list>

9. 5. 3. CDATA

Can't contain CDATA.

9. 5. 4. Default constructor

intance="new java.util.ArrayList()"

9. 6. Element type Map

9. 6. 1. Purpose

Makes it easy to create and populate a java.util.Map instance.

9. 6. 2. Additional value element handling

All additional value elements are interpreted as entries in the Map. The name of the element is used as the key and the element instance as the value.

Here is an example of how to create a Map manually:

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.jicengine.org/jic/1.0"  instance="new java.util.HashMap(initialSize)">
  <initialSize  instance="2"/>
  <element  action="PARENT.put(key,value)">
    <key  instance="'key1'"/>
    <value  instance="'value1'"/>
  </element>
  <element  action="PARENT.put(key,value)">
    <key  instance="'key2'"/>
    <value  instance="'value2'"/>
  </element>
</map>

Here is the configuration of a same Map when the element type map is used:

<?xml version="1.0" encoding="UTF-8"?>
<map xmlns="http://www.jicengine.org/jic/1.0"  type="map"  instance="new java.util.HashMap(initialSize)">
  <initialSize  instance="2"/>
  <key1  instance="'value1'"/>
  <key2  instance="'value2'"/>
</map>

NOTE: Only a Map whose keys are Strings can be created. If other type of keys are required, one must create the Map manually.

9. 6. 3. CDATA

No CDATA is allowed.

9. 6. 4. Default constructor

new java.util.HashMap()

9. 7. CData element types

CData element types are used for parsing CDATA sections into Java objects. They all provide a default constructor. Child elements will not be allowed.

The table below summarizes the default constructors and accepted CDATA content of the element types.

Element type Element instance type Default constructor and accepted CDATA
int java.lang.Integer

java.lang.Integer.parseInt(CDATA)

Accepts integer values

<value  type="int">123</value>
<value  type="int">0</value>
double java.lang.Double

java.lang.Double.parseDouble(CDATA)

Accepts double values

<value  type="double">12.0</value>
<value  type="double">0.0</value>
float java.lang.Float

java.lang.Float.parseFloat(CDATA)

Accepts float values

<value  type="float">12.1234</value>
<value  type="float">-1234.0</value>
long java.lang.Long

java.lang.Long.parseLong(CDATA)

Accepts long values

<value  type="double">123</value>
<value  type="double">12345678L</value>
boolean java.lang.Boolean

java.lang.Boolean.valueOf(CDATA)

Accepts boolean values

<value  type="boolean">true</value>
<value  type="double">false</value>
font java.awt.Font

java.awt.Font.decode(CDATA)

Format is specified by java.awt.Font.decode()

<font  type="font">Arial-bold-12</font>
<font  type="font">Helvetica-10</font>
<font  type="font">Times-italic-24</font>
color java.awt.Color

[constructor internal to JICE]

Accepts RGB or RGBA color values. Color channel values can be specified both as numbers between 0-255 or hex numbers 0-F.

<color  type="color">255,127,0</color>
<color  type="color">255,127,0,255</color>
<color  type="color">FF9900</color>
<color  type="color">FF9900FF</color>
resource org.jicengine.io.Resource

[constructor internal to JICE]

Accepts a file path that is relative to the JIC file.

<file  type="resource">config/app.properties</file>
<image  type="resource">../images/flower.gif</image>

10. JIC attributes

10. 1. type="typeName"

Specifies the JIC element type of the element. See below.

Optional. Defaults to 'bean'.

10. 2. instance="LJE expression"

Specifies the constructor - an operation that creates the instance of the element.

Optional.

10. 3. action="LJE expression"

Specifies the action of the element.

Optional.

10. 4. class="full.class.name"

Specifies the type of instance of the element.

The class attribute has two purposes:

  1. It is an alternative way for specifying the constructor. It is used, together with the parameter 'parameters', for creating an implicit constructor.
  2. It can serve as a type constraint. The element instance must be an instance of this class or an instance of its subclass.

Optional.

Example values:

10. 5. parameters="LJE parameter expression"

Specifies the parameters given to the implicit constructor. Attribute 'parameters' must be used together with the attribute 'class'. The attribute 'instance' is not allowed to be used together with 'parameters'.

Optional.

10. 6. id="idString"

Gives a global id to the element instance. Other JIC elements can reference the instance with this id. This can be thought of as declaring a global variable whose value is the element instance.

Optional.

10. 7. overridable-by="parameterName"

Makes it possible to override the element instance by a build parameter.

Optional.

11. JIC Language and XML Namespaces

JIC Engine accepts only XML elements that are in the JIC namespace http://www.jicengine.org/jic/1.0. All other elements will cause an error when a JIC file is processed.

NOTE: elements in other namespaces could be allowed in the future, if there would be a reason to accept them.

Attributes that have no namespace or that are in the JIC namespace http://www.jicengine.org/jic/1.0 are interpreted as JIC attributes.

However, attributes that belong to other namespaces are silently ignored.

It is therefore possible that the elements in a JIC file have some non-JICE attributes. The rationale is that applications could add some application specific meta-data into the elements if necessary.