JeeWiz Architect's Guide - Finding A Value


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 7. Finding Values and Files

7.3 Finding A Value

We now explore what triggers the end of a search for a substitution value - when a 'value is found', to quote the previous section.

The basic rules are:

From the model object's JavaBeans style properties, a value is found if a property of this name exists on the object. This can be null-valued.
From all other locations, a value is found if a non-null value is found in the appropriate lookup table. In practice - unless you write Java code to explicitly set some of these values to null - if a value exists in one of the lookup tables, then it will be non-null anyway.

So, in practice the searches described in the previous sections do stop when a value is found.

You will have to take account of the situation where a value is null. For example, many of the code-generating scripts have the sequence:

#if ( $package )
    package $package;
#end

This tests whether the package property is non-null before including the package statement.

7.3.1	Delegating Values
7.3.2	Beware 'if( $name )'

7.3.1 Delegating Values

In some situations, you don't want to stop the search to find a value if a null is found on a model object. You then want to delegate the search to the parents and outer configuration to find a non-null value.

The 'package' property is a good example of this. 'Package' is a property on ObjectModel 'Jwclass' and 'Interface' objects (and therefore all their descendants); this is the normal Java 'package' concept. To provide sensible defaults for classes (particularly from UML models), JeeWiz also has the package concept on class containers, like jars, ejb-jars and applications. This means that, if the package is not specified for a class or interface, it should be deduced from the parents, which will be, depending on the type of build, the jar or ejb-jar and application.

Therefore the package property is marked 'delegated', which means that a particular class or container does not need to set its package property - it can use one from its parent. This turns out to be very convenient: you can easily change the packaging structure for a whole tree by, say, changing the 'package' property on an ejb-jar.

It is common practice to have a default for delegated properties in the appropriate template directory's system.properties. For example, in resources/java/control/system.properties, there is the line

package=jeewiz.test

This sets a default package for the whole build, which means the modeler does not have to worry about packages in simple models. Furthermore, this can be overridden for a particular build (in the build.jwp file or in a calling Ant script).

Another example of a delegated property is 'constraintExceptionType' which specifies the exception type to be thrown when a constraint fails. This is specified on constraints, classes, jars and applications, and also in bizobject/control/system.properties. Because this is an architectural property, it is quite likely that modelers will not set this value. It can be set just once (typically in the build.jwp file or in a calling Ant script) so that it applies to a whole application.

These examples illustrate the following rules:

Delegated properties must be Strings or booleans.
The search for a delegated value covers all parent meta-classes and then the start-of-day project. It is precisely the same as a normal search for an Ant or Velocity property. This means it is good practice for an architect to set a default for a delegated property in the system.properties file in the appropriate template directory (e.g. resources/bizobject/control) if it is a feature of the application.

To override the default defined in system.properties, set the value in the build properties *.jwp file.
Although some delegate properties, like 'package', are defined on the complete chain of parent meta-classes (e.g. class, jar/ejb-jar, application), the delegation mechanism also works if the delegated property is not defined on the parent meta-classes. For example, record versioning is invoked via the 'version-control' property on an entity. There is no particular point in defining this on the ejb-jar or application, so there is no delegated property there. However, as this is an architectural feature, the default (record versioning off or on) is defined in bizobject\control\system.properties. This can be overridden in a project-specific meta-model, or in the build.properties.

7.3.2 Beware 'if( $name )'

The search order described in the previous section has an important 'gotcha'. In some cases, the code may request a search up the model object tree when none is intended.

The most common case is writing 'if( $name )'. It is easy to intend this to say "if the current model object has a name value", forgetting that this invokes a search up the model object tree.

The way to stop the search is to use 'if( $this.name )'. When the value is requested of a particular model object, the search up the model object tree is not done.

This is only an issue for non-delegated properties; for delegated properties like 'package', writing $package or $this.package immediately finds the delegating property on the object, which automatically starts the delegation process if no value has been set on the current model object.