JeeWiz Home  
The Model-Driven System Builder

JeeWiz Architect's Guide
 
Contents  >   7.  Finding Values and Files
 

7.2 Finding And Using Properties

From the diagram in the previous section, we can see that there are a number of ways in which properties are stored.

  1. As properties on the first project for the JeeWiz run. The start-of-day configuration items go here, as described in the 'start-of-day' configuration process . These values are set only by start-of-day configuration.
  2. As values attached to a model object. There are two ways in which a model object holds values:
    1. As JavaBean-like properties, accessed via getter and setter methods on the meta-class. For example, the name property (which is available on all meta-classes) is read via 'getName()' and set via 'setName(String)'.
    2. As extra properties, on a private 'properties' HashMap held by the object. (This is accessible in Velocity as '$properties' and in Java as 'getProperties()'). A property is put into the properties HashMap if there is no public JavaBean style set method.

      As we will see later, values from this HashMap are available to Ant tasks or Velocity scripts in much the same was as the JavaBean properties.
    These values are set in the following ways:
    • Normal Java defaults, or constructor code executed by the objects
    • Read-in of the XML script
    • From processing the component.properties file.
    • From patterns and templates.
  3. As properties on an Ant script. When an Ant script is being run for a particular model object, there is an Ant project associated with that object, and the Ant project can have properties set on it using the Ant <property> task.
  4. As Velocity variables. Any unqualified value you set in Velocity using #set is stored in a local Velocity context for the processing of that particular Velocity script.
During substitution in Ant and Velocity, JeeWiz implements a search order which continues until a 'value is found'. This will normally be until one of the places searched returns a non-null value. The details are given in the following sub-sections, but the intent of the mechanism is as follows:
  1. Use start-of-day properties to match the generated system to your company standards. In particular, override assignments of literals (e.g. 'buildSubDir=build') to change directory structures and change the JeeWiz build.properties to match your local environment.
  2. Use properties in Ant build jobs purely for conditions local to the Ant build job - e.g. for conditions set locally, like the result of the <uptodate> task. These properties are not visible outside the Ant job.
  3. Use properties on the Java object for values read from the XML specification - which should not be changed by the JeeWiz build - and for accessing object methods that do Java processing.
  4. Use extra properties set via component.properties to implement local naming standards and change any other calculated values for processing the object. If you are used to building Ant, then most of the object and directory/file naming that is done in Ant <property> tasks should be done via component.properties. It is easier to set up properties in the component.properties file than in Ant scripts, and they will also be available (a) in Velocity scripts and (b) to children.
In the following descriptions, the location numbers refer to the numbers in circles in the diagram in the first section.

 7.2.1  Property Read From Ant
 7.2.2  Property Read From Velocity Script
 7.2.3  Property Write From Ant
 7.2.4  Property Write From Velocity
7.2.1  Property Read From Ant
When an Ant project looks up a property value for substitution, the lookup order is
  1. [ Location 1 is not applicable, because this is not a Velocity task. ]
  2. Location 2 - the property values in the current Ant project.
  3. Location 3 - the JavaBeans properties on the current model object.
  4. Location 4 - the properties in the HashMap attached to the current model object.
  5. Location 5/6 - repeat items 3/4 for the parent (application) object.
  6. Location 7 - finally, start-of-day configuration items are searched.
We have only shown one Ant project down at the EJB Jar level. Of course, the uptodate.xml and build.xml files for a particular level may call other Ant projects or start off other Java JVMs.

The particular search order for Ant projects described here is only applicable to JeeWiz-started projects: other Ant tasks you start off using the <ant> or <antcall> tasks will not have this searching capability, so any values you need there will have to be passed in as properties.

However, there is a special JeeWiz variant of the <ant> task you can use to invoke other Ant scripts, called 'jwAnt': this does tie into the property-searching mechanism described above and so give access to values on model objects. See the section on Ant Tasks for details.
7.2.2  Property Read From Velocity Script
When a Velocity script looks up a variable's value for substitution (e.g. '$name'), the lookup order is
  1. Location 1 - the current context. This is where all unqualified variables (e.g. no '.' in the name) are set.
  2. [Location 2 is skipped - we don't use the Ant properties when looking up Velocity variables]
  3. Location 3 - the JavaBeans properties on the current model object.
  4. Location 4 - the properties in the HashMap attached to the current model object.
  5. Location 5/6 - repeat items 3/4 for the parent (application) object.
  6. Location 7 - finally, start-of-day configuration items are searched.
If we compare this lookup sequence with reading from Ant, they only differ in the starting point: instead of starting with the Ant properties, the Velocity variable lookup starts with the Velocity context. The rest of the lookup chain is the same.

[If you are familiar with Velocity, this is a variant of Velocity's "velocimacro.context.localscope=true" operation. In Velocity, this mode hides values in the current context: in JeeWiz, we first try the local VM context - which will be values that have been #set, then try the remainder of the context.]
7.2.3  Property Write From Ant
When you set a property in Ant, it goes into the current project. For example, in the diagram above, if you use the <uptodate> task in the ejb-jar/build.xml, it will get set in the properties for that Ant task (location 2).

The implication of the way we lookup values overall is that values you set in this way are only available via JeeWiz in this Ant task and its immediate Ant descendants (e.g. <ant> or <antcall> tasks). It will not be available in Velocity scripts that are invoked by this Ant script or invoked Ant scripts.
7.2.4  Property Write From Velocity
Velocity provides the #set directive for setting variable values. See the Velocity User's Guide for details.

The simplest form is 

#set ( $variable="value" )
Local variable assignments like the above (with no '.' qualifier) always go into the Velocity context. This uses a private HashMap inside the Velocity context to store local variables. JeeWiz instantiates a new Velocity context for each Velocity template or patteren that is run, so local variables do not carry across.

[If you are familiar with Velocity, this is consistent with "velocimacro.context.localscope=true" operation: we always set the value in the local scope.]

It is also possible to deliberately set values in the model objects, using references to model objects and qualifiers. See the section 'Setting Values In The Object Model' for details.  

Copyright (c) 2001-2008 New Technology/enterprise Ltd.