JeeWiz Architect's Guide - JeeWiz Controls


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 2. Overview

2.10 JeeWiz Controls

JeeWiz controls, also referred to as 'generate-time controls' - or just 'controls' where the context is clear - are Java objects outside of the model object tree that generate text or other values for use in a rendering (either pattern or template).

The main benefit of JeeWiz controls is to separate the concerns of rendering from (a) the minutiae of the generated code and (b) changes for local configuration. By using JeeWiz controls, the meta-programmer can create renderings, templates in particular, that can be used unchanged on different platforms and configurations.

An important implication of this approach is that renderings can be used in environments not anticipated by the meta-programmer: a new meta-model or customer project can define or configure the JeeWiz controls used without changing the renderings that use the controls.

A subsidiary benefit of JeeWiz controls is that they factor out common sequences of logic; these can be referenced as properties of the control from the rendering, reducing the total volume of meta-program code to be written.

2.10.1	Motivation
2.10.2	Application Areas
2.10.3	Using Controls
2.10.4	Variations

2.10.1 Motivation

To initialise a variable to a 'nothing' value, the code for an object reference will be

$type $name = null;

or, for a boolean:

$type $name = false;

In earlier versions of JeeWiz, this led to code such as the following to declare a variable:

#if( $type == "boolean" )
    $type $name = false;
#elseif( $type == "int" )
    $type $name = 0;
...
#end

JeeWiz controls allow the meta-programmer to generate the variability here - 'null' or 'false', or '0' for integers - without resorting to the Velocity #if statement. Further details of this example and the benefits of controls are described later.

2.10.2 Application Areas

JeeWiz provides a number of pre-constructed types of controls:

Language	Has a list of keywords (so templates can avoid generating them) and substitutions for standard properties in case you want to write language-independent code. For example, if we want to get the number of items in an ArrayList in a language-independent way, we should write (`$lang.subst.ArrayList.Count`) if $lang is the language control, and it will evaluate to `size()` in Java.
Physical Datatype	The 'physical' datatypes are the fundamental types of the current language - as used in the example above. The controls give details of null/empty values, whether the value needs to be handled in a certain way (e.g. is it a date, numeric etc.) and conversions between the stored types and other representations like strings or XML-compatible dates.
Logical Datatype	The 'logical' datatypes are the types use in models. As well as the basics (string, boolean, char etc.), there are things like currency, wrappedInt/Long etc, duration, isoDate/Time. Using controls for logical datatypes gives the programmers a structured way of extending the modelling environment; there is a parallel feature for modellers to extend logical types for their own purposes (see 'atomic-type').
Java SQL Type	A physical data type is stored to a database using a different type. This is common with booleans - they tend to be mapped to characters, strings or numbers on the database. The Java SQL Type control describes how types are mapped, for presentation to the ORM product like Hibernate or J2EE. If a customer has a particular type of mapping of a datatype, this can be addressed by building a new Java SQL Type control.
Database	Database controls are used to create DDL - to drop and create tables, link tables, keys and constraints - and SQL phrases for direct access (i.e. without going through the ORM layer).
UI controls	The UI controls generate the code or script and associated configuration to display data and actions on pages. Of course, run-time architectures have UI controls too. The JeeWiz controls don't do the run-time work: they provide a way of programming UI pages independent of the details of the code/configuration required to generate the pages.
Logging	Logging controls are provided as default for output using System.out.println(); JDK 5 and log4J loggers can also be created. These controls can also filter how much logging code is generated (in addition to the usual run-time filtering).

2.10.3 Using Controls

Controls are usually created by startup code, placed into a HashMap, which is then loaded into the $C variable, which is used by convention for controls only. For example, $C.PDT holds the physical datatype controls and $C.PDT.boolean is created to define the Java 'boolean' type. Similarly $C.LDT holds logical datatype controls.

This structure allows controls of a certain type to be looked up by 'name' - like "boolean" in the previous example. The controls often allow lookup by style (i.e. get me a UI control for a field using a drop-down, with String datavalues).

2.10.4 Variations

It is important that controls can be enhanced, by overriding existing controls or adding new controls. This is easy to do without changing existing code.

For example, to create a brand new logical datatype control, the programmer

creates a new template directory and a start.vm script within it
writes the control in a file, e.g. "myNewLDT.control"
in start.vm, writes code to instantiate an instance of the object and then places it into the appropriate table, e.g.:
#set( $C.LDT.myNewLDT = $this.getNewControl( "myNewLDT" ) )

When the new template directory is included in a build, the "myNewLDT" control will become available for use as a logical datatype in modelling.

To override an existing control, the start.vm control puts the new control into the $C table using the same index (or indexes) as the existing control. There is no need to alter existing code. The new control will only be used when the new template directory is used as an override.