JeeWiz Architect's Guide - The Template Directory


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 6. Running And Configuring JeeWiz

6.5 The Template Directory

The template directory is a special type of directory that has files that control a JeeWiz build. It defines the 'rendering' - how a model will be converted into the generated files. For example, in a J2EE system, the rendering defines that the end products will a Java Jar, or an application 'ear' for WebLogic, for instance.

A template directory is often paired with the meta-model for a particular layer. For example, the jeewiz/resources directory has the 'bizobject' directory which demonstrates these two parts:

the directory holding the XML for the meta-model specification (e.g. that the meta-model has a concept of 'application', and that an application can have 'ejb-jar' elements nested underneath it). In the standard JeeWiz distribution, this is the 'specification' directory. For the bizobject meta-model, this directory is jeewiz/resources/bizobject/specification.
the default template directory, which is the 'control' directory in the standard JeeWiz distribution. For the bizobject meta-model, this directory is jeewiz/resources/bizobject/control.

Putting the template directory as a peer of the meta-model directory makes sense when there is a default rendering for a meta-model.

We sometimes loosely refer to the 'meta-model directory' as a synonym for 'template directory'. However, there is a way of specifying a non-default rendering for a meta-model, so 'template directory' is the correct term.

A JeeWiz generation usually involves many template directories, as described here The list of template directories, and the order they appear in, determine what is generated. This list is specified in two ways, both of which start from 'templateDir' property, which can be:

a single directory, in which case it specifies the initial template directory. This directory becomes the first directory in the list. The next directory (or directories) are defined in the 'parent' property in the model.properties file in the referenced template directory. The next template directory also must have a model.properties file, and it too can have a 'parent' property, which continues the process of adding to the template directory list. This process terminates when the model.properties file has no 'parent'.
a list of directories. When there is more than one directory, the 'parent' property in the model.properties file is not followed. In other words, the 'templateDir' property specifies the complete list of directories, and the order they should appear in.

A list of directories, in 'templateDir' or 'parent' properties, consists of directory paths separated by the path separator character (':' on UNIX, ';' on Windows) or ','. By using the ',', a list of paths is guaranteed to work on UNIX and Windows (at the expense of disallowing ','s in directories on Windows). Furthermore, leading and trailing whitespace is trimmed from each element in the list before being used as a directory name.

Whichever approach is used to specify the list of template directories, the complete list of template directories in the current build is available in the $templateDirectoryList variable. This is put into the outermost context, so you can reference it in any template (as long as it is not overridden). The class for this variable is java.util.Vector; each element in the Vector is a java.io.File object pointing to the template directory. The order is most-precedent first, so item 0 is the "top-most" template directory. This can be used, for example, to copy all the images from the source template directories into a web application. The following snippet shows the construction of the <fileset> elements inside an Ant <copy> task:

#foreach( $file in $templateDirectoryList )
   #set( $thisTemplateDir = $this.getFile( $file, "$additionalImagesSubDir" ) )
   #if( $thisTemplateDir.isDirectory() )
               <fileset dir="$thisTemplateDir">
   #end
#end

The template directory has the following files. These are all optional except for the model.properties file:

model.properties	A description of the model. This is key to model chaining. The model.properties file is described in the next section. This file is required if a directory is used as a template directory.
system.properties	This file holds descriptions and default values for all the top-level properties used by the model. For example, see the system.properties file for the J2EE model. When you define system properties in this file, you should make this file the main reference for the meaning of the properties; in other words, write copious comments as documentation list properties that cannot be calculated (and therefore must be specified by the user if they need to be changed), before properties that are calculated. The ordering is important, and references to a property before it is defined in the file will be undefined. Template directories do not have to have a system.properties file, but in practice they usually do. Any properties that are defined here can be overridden by the user in the build properties (*.jwp) file.
template.properties	This file links between meta-class types to implement inheritance in rendering (as opposed to Java-style inheritance at the meta-model level). Details are in The template.properties File.
components.jar	components.jar must contain the Java classes for the meta-classes and any other related objects. For example, in the J2EE components.jar, there are Java classes named Application, EjbJar, Session etc. A template directory does not need a components.jar, if there is no extra 'model' information - the template directory then just specifies a rendering. This makes perfect sense. For example the JBoss3 template directory (as of this writing) only contains configuration and rendering information additional to the J2EE model, but no components.jar.
*.jar	Of interest to meta-model writers only. Any other jars that are required to read the model can be put in this directory and they will be automatically added to the JeeWiz run. These are JeeWiz model files and are only used to edit or build using JeeWiz; they are not propagated forward into run-time classpaths.
system.methods	These are Velocity-based methods that are globally available, independent of the location of a call to the method or the object that it is used on.
start.vm	This file holds Velocity code that will be executed before the rendering starts. This gives the meta-programmer a chance to perform start-of-day tasks such as check and fix up the top-level component create any required JeeWiz controls as described in Using Controls. 'start.vm' is executed once the specification has been read and all the top-level properties from .jwp files and system.properties in the template directories have been set. 'start.vm' execution immediately precedes the pattern phase. 'start.vm' is applicable to additional specifications as well as the main specification. There can be many start.vm files for a given stack of template directories. In this case, the start.vm files are all executed, with the start.vm from the least-precedent template directory being executed first.
finish.vm	This file holds Velocity code that will be executed after all patterns have been processed but before any templates are run, to generate output files.
<metaClass>/*	Model objects can be individually 'rendered' (built) by placing an Ant build.xml file and any supporting files in a directory named after the meta-class. The complete list of files in this directory are: `component.properties` - component properties specific to this type of model object. `component.methods` - methods specific to this type of model object. `build.xml, uptodate.xml` - the Ant build files `includeSpec.vm` - the patterns for this file. `.vm, *.inc etc.` - any template or include files to support the build and pattern processes `template.properties` - diversion signs, to tell the lookup mechanism to include or goto another type of object. For example, the directory jeewiz/resources/j2ee/control/application holds the build.xml and Velocity scripts for the J2EE application object.