The concept of performing a rules-directed conversion of elements and attributes into Java objects was pioneered (to my knowledge) in the Jakarta Digester framework (which started inside Tomcat, moved to Struts, and is now available on its own).
The technique is very powerful, even in the limited subset of Digester provided by Gaderian (over time, the number of available rules will increase).
Rules are attached to <element>s. Each rule object has two methods: the begin() method is invoked when the element is first encountered. The content of the element is then processed recursively (which will involve more rules). Once that completes, the end() method is invoked.
Note: begin() is invoked in the order that rules are
defined within the <rules> element. end() is invoked in
inverse order. This rarely makes any difference.
Element processing is based on an object stack. Several rules will
manipulate the top object on the stack, setting properties based on
attributes or content. The <create-object> rule will instantiate a new
object at begin() and pop it off the stack at end()
.
In several cases, rule descriptions reference the parent and child objects. The top object on the stack is the child, the object beneath that is the parent. The <set-parent> and <invoke-parent> rules are useful for creating hierarchies of objects.
The <create-object> rule is used to create a new object, which is
pushed onto the stack at begin(). The object is popped
off the stack at end(). <create-object> is typically
paired up with <invoke-parent> to connect the new object (as a child)
to a parent object.
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| class | string | yes | The complete class name of the object to create. The class must be public, and have a no-arguments public constructor. The class name may be abbreviated; it is resolved by the module containing the <schema> element. You may use instance initializer syntax. |
The <custom> rule is used to provide a custom implementation of the
Rule interface. Note that any such rules must not contain
any individual state, as they will be reused, possibly by multiple
threads.
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| class | string | yes | The complete class name of the class implementing the Rule
interface. |
The <invoke-parent> rule is used to connect the child (top object on
the stack) to its parent (the next object down). A method of the
parent is invoked, passing the child as a parameter. This invocation
occurs inside the rule's begin() method; to ensure that
the child object is fully configured before being added to the parent
place this rule after all properties of the child object have been
configured.
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| method | string | yes | The name of the method to invoke on the parent object. |
| depth | number | no | The depth of the parent object within the object stack. The top object (the child) is at depth 0, and default depth of the parent is 1. |
addElement
. This adds the created,
configured object to the list of contributed objects for the
<contribution>
(or for service factories, adds the object as a parameter). The <push-attribute> rule reads an attribute, converts it with a translator, and pushes the result onto the stack. It will typically be combined with a <invoke-parent> to get the pushed value added to the configuration point elements (or to some parent object).
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| attribute | string | yes | The name of the attribute to read. |
The <push-content> rule reads the content, converts it with the content translator, and pushes the result onto the stack. It will typically be combined with a <invoke-parent> to get the pushed value added to the configuration point elements (or to some parent object).
The <read-attribute> rule reads an attribute from the current element, optionally translates it (from a string to some other type), and then assigns the value to a property of the top object on the object stack.
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| property | string | yes | The name of the property of the top object on the stack to update. |
| attribute | string | yes | The name of the attribute to read. |
| skip-if-null | boolean | no | Represents the policy employed when the to be read attribute was omitted and has no defined default value. If "true" (the default), then an omitted attribute without default value will be ignored. If "false" the property will be updated with "null" or, if defined, the default value. |
| translator | string | no | A translator that overrides the attribute's translator. |
The <read-content> rule is similar to <read-attribute>, except it concerns the content of the current element (the text wrapped by its start and end tags).
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| property | string | yes | The name of the property of the top object on the stack to update. |
<set-module> is used to set a property of the top object on the stack to the module which made the contribution. This is often used when some other attribute of the contribution is the name of a service or configuration extension point (but it is advantageous to defer access to the service or configuration). The module can be used to resolve names of services or configurations that are local to the contributing module.
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| property | string | yes | The name of the property of the top object to update with the contributing module. |
The <set-parent> rule is used to set a property of the child object to parent object. This allows for backwards connections from child objects to parent objects.
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| property | string | yes | The name of the property of the child object to set. |
The <set-property> rule is used to set a property of the top object to a preset value.
| Attribute | Type | Required ? | Description |
|---|---|---|---|
| property | string | yes | The name of the property of the child object to set. |
| value | string | yes | The value to set the proeprty to. The is interpreted as with the smart translator, meaning that conversion to normal Java types (boolean, int, etc.) will work as expected. |
Commonly, it is necessary to perform some translation or transformation of string attribute value to convert
the value into some other type, such as boolean, integer or date. This can be accomplished by specifying a
translator in the <attribute> element (it also applies to element content, with the
content-translator attribute of the <element> element).
A translator is an object implementing the Translator interface. The translator value
specified in a rule may be either the complete class name of a class implementing the interface, or one of a
number of builtin values.
Translators configurations consist of a translator name, and an optional initalizer string. The initializer
string is separated from the translator id by a comma, ex: int,min=0 (where min=0 is
the initializer string). Initializer strings are generally in the format of key=value[,key=value]*
... but each Translator is free to interpret the initializer string its own way.
The following sections describe the basic translators provided with the framework. You can add additional translators by contributing to the gaderian.Translators configuration point.
The boolean translator converts an input string into a boolean value. "true" is translated to true, and "false" to false.
A default value is used when the input is blank. Normally, this default is false, but the "default" key in
the initializer can override this (i.e., boolean,default=true).
The class translator converts a class name into a Class object. The value must be a fully qualified class name. A null input value returns null.
The configuration translator converts an input value into a configuration point id, then obtains the elements for that configuration point as a List. The id may be fully qualified, or a local id within the contributing module.
A blank input value returns null.
The double translator converts the input into an double precision floating point value. It recognizes three initializer values:
The enumeration translator converts input strings into enumerated values. Enumeration requires an
initializer string, with a special format:
enumeration,class-name,input=field-name[,input=field-name]*
That is, the initializer begins with the name of the class containing some number of public static fields.
Input values are mapped against field names. Example:
enumeration,java.lang.Boolean,yes=TRUE,no=FALSE
If the input is null or empty, then the translator returns null.
The class name for the enumeration may be abbreviated.
Translates a comma-seperated list of ids into a comma-seperated list of fully qualified ids (qualified
against the contributing module). Alternately, passes the value * through as-is. Id lists are
typically used to establish ordering of items within a list, as with <interceptor>.
The object translator converts a fully qualified class name into an object instance. The class must implement a public no-arguments constructor.
The class name may be abbreviated.
The instance translator may also initialize properties using instance initializer syntax.
The int translator converts the input into an integer value. It recognizes three initializer values:
The long translator converts the input into an long integer (64 bit) value. It recognizes three initializer values:
The object translator is allows the caller to provide an object value in a multitude of ways. The object translator inverts the normal roles; the caller has all the power in determining how to interpret the value, and the schema takes whatever value shows up. The object translator is driven by the gaderian.ObjectProviders configuration.
Some object providers include a class name, which may be abbreviated and will be resolved by the contributing module.
Translates an id into a fully qualified id (qualified against the contributing module's id).
The resource translator is used to find a resource packaged with (or near) the module's deployment descriptor. The input value is the relative path to a file. The translator converts the input value to a Resource for that file.
If the file doesn't exist, then an error is logged. If a localization of the file exists, then the Resource for that localization is returned.
The service translator is used to lookup a service in the registry. The input value is either a local service id from the contributing module, or a fully qualified service id.
The service translator is used to lookup a service point (not a service) in the registry. The input value is either a local service id from the contributing module, or a fully qualified service id.
The smart translator attempts an automatic conversion from a string value (the attribute value or element content) to a particular type. It determines the type from the property to which the value will be assigned. Smart translator makes use of the JavaBeans's PropertyEditor class for the conversion, which allows easy this translator to be used with most common primitive types, such as int, short and boolean. See the SmartTranslator documentation for more details.
In general, the smart translator is the useful for most ordinary Java type properties, unless you want to specify range constraints.
It recognizes one initializer value: