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!".
<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
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:
-
JIC Language has 14 different element types.
-
object
,bean
,block
,array
,list
,map
,int
,double
,long
,float
,boolean
,color
,font
andresource
.
-
- All of the 14 element types are subtypes of the a general JIC element. They differ from each other in only a few things.
- The name of an XML element doesn't signal the element type of the element.
- The name is used for other purposes - the names depend on the Java API that is used and on the decisions on the author of the JIC file.
- The JIC attribute
type
specifies the element type of an XML element. - There aren't elements
<bean>
,<block>
,<array>
, etc. - There can be elements
<something type="bean" ..>
,<somethingelse type="block" ..>
,<another type="array" ..>
, etc.
- JIC Language doesn't specify a finite set of XML elements. However, it specifies the structure and semantics of a JIC element, and every XML element in a JIC file is a JIC element.
-
The XML elements must belong to the JIC namespace
http://www.jicengine.org/jic/1.0
and they must contain JIC attributes.
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:
- initialize a Java instance.
- execute an action.
- 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:
- 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.
- 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:
- the necessary parameters are created (or obtained).
- the Java instance is created (or obtained):
- a Java class is instantiated with the
new
operation. - an instance is obtained from a factory.
- etc.
- a Java class is instantiated with the
- 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:
- the necessary parameters are created (or obtained).
- 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:
<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:
- the constructor parameters are obtained from child elements
<year>
,<month>
and<date>
-
<calendar>
creates thejava.util.GregorianCalendar
instance. -
elements
<lenient>
and<timeZone>
set the properties lenient and timeZone of thejava.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:
- It always has a name
- It might have a constructor .
- It might have an action .
- It might have an id .
- It might have inner JIC elements as children:
-
inner value elements
- elements used as constructor parameters
- elements used as action parameters
- other elements. (called additional value elements)
- inner action elements
-
inner value 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:
|
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:
|
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:
- inner value elements that are constructor parameters.
- additional value elements and inner action elements. (these elements can be mixed. The best order depends on the situation.)
- 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
:
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:
<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:
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:
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>
:
<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:
<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
:
<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:
<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:
- element instances of the inner value elements.
- the element instance of the parent element.
- global instances.
- 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:
- If the element has an inner value element with the same name, the variable refers to the element instance of that child element.
- If none of the child elements match, the variable refers to a global instance with a matching
id
. - 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 name of the JIC element itself is not available inside the element. The action must use the variable
this
and the children must use the variablePARENT
. - A JIC element can't refer to its inner action elements, only to inner value elements.
- Because of this, the names of the action elements don't actually have any meaning.
- local objects (inner value elements) override global instances
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
<locale xmlns="http://www.jicengine.org/jic/1.0" instance="new java.util.Locale(language,country)">
<language instance="'fi'"/>
<country instance="'FI'"/>
</locale>
4. 1. 2. Referring to the element instance of the JIC element itself
<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
<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:
- child elements are executed one by one, until all inner value elements needed in the constructor are processed.
- The constructor of the element is executed, which yields the element instance of the element.
- Rest of the child elements are executed, again one by one.
- The element instance is now fully initialized. It is made a global instance, if necessary (if the element has the
id
attribute). - 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:
<list2 class="java.util.ArrayList"/>
The parameters
attribute is needed, if there are constructor parameters:
<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:
- the constructor might refer to the value of a variable
- the constructor might be a method invocation that obtains the element instance from some factory.
- etc.
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:
<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:
- asserts that the object returned by the constructor is an instance of a certain class. If not, an exception is thrown.
- 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:
<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:
<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>.
<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:
- The parameter can
override the element instance of a JIC element. - 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
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
.
<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:
- Only inner value elements that are used as action parameters will be executed.
- all other inner value elements (constructor parameters and additional value elements) are skipped.
- all inner action elements are skipped.
- The constructor of the element is not executed.
- If the element has an
id
, the value of the overriding parameter is made a global instance. - 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.
For example, if the following JIC file is processed with the parameter message
, the element <inner-action-element>
will never be executed.
<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:
- How the element handles its additional value elements i.e. inner value elements that are NOT used in the action or constructor.
- Some of the types specify a default constructor for the element and constrain the type of Java objects the element can initialize.
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 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:
-
Child element types
- these types are based on different policies for handling the additional value elements.
- object - A simple element that doesn't allow additional value elements. Can be used for configuring any Java object, although the type bean is probably more convenient.
-
bean -
(default) Useful for configuring objects that have bean-like properties. - block - a block of JIC code. useful for instantiating large, complex object graphs.
- array - provides a way to create and populate object and primitive arrays.
-
list - provides an easier way to create and populate a
java.util.List
than possible with the bean-type. -
map - provides an easier way to create and populate a
java.util.Map
than possible with the bean-type.
-
CData-types
- for parsing CDATA content into objects.
-
int - parses CDATA into int (
java.lang.Integer
object) -
double - parses CDATA into double (
java.lang.Double
object) -
boolean - parses CDATA into boolean (
java.lang.Boolean
object) -
long - parses CDATA into long (
java.lang.Long
object) -
float - parses CDATA into float (
java.lang.Float
object) -
color - parses CDATA into
java.awt.Color
object -
font - parses CDATA into
java.awt.Font
object -
resource - parses CDATA into
org.jicengine.io.Resource
object
-
int - parses CDATA into int (
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:
<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:
<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:
<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:
<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>
<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:
<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:
<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:
<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:
<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
|
Accepts integer values <value
type="int">123</value>
<value type="int">0</value> |
double |
java.lang.Double
|
Accepts double values <value
type="double">12.0</value>
<value type="double">0.0</value> |
float |
java.lang.Float
|
Accepts float values <value
type="float">12.1234</value>
<value type="float">-1234.0</value> |
long |
java.lang.Long
|
Accepts long values <value
type="double">123</value>
<value type="double">12345678L</value> |
boolean |
java.lang.Boolean
|
Accepts boolean values <value
type="boolean">true</value>
<value type="double">false</value> |
font |
java.awt.Font
|
Format is specified by <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:
- It is an alternative way for specifying the constructor. It is used, together with the parameter 'parameters', for creating an implicit constructor.
- 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.