|
JeeWiz Architect's Guide
|
|
|
|
Contents >
10. JeeWiz Controls
|
|
|
10.2 Structure of JeeWiz Controls
A JeeWiz control is a file that falls into three parts. This section describes the parts of a control, and the details of using them.
10.2.1 Control Files
|
Each control is coded in a file named x.control, where x is the name of the control.
Only one control can be coded in a control file.
For the control to be found, the control file must be in a template directory that is in the list of template directories for this build.
As for other files in JeeWiz, the position of the template directory in the list of template directories is significant:
it affects overriding.
.control as a file extension in template directories is reserved for controls.
Strictly, the .control extension it is not significant elsewhere - you can use if for templates or #parse files.
In practice however, this is not recommended: it makes life easier for maintainers if only controls are given the .control extension.
The name is case sensitive. In other words, a control in the file x.control will not be found under the control name "X".
Although no checks are made, you should only use alphanumeric and "_" characters in the name of the control.
The name of the control must be usable as a file name and also as a Velocity word, as we will see next.
10.2.2 Parsing and Comments
|
The control file is parsed first as a Velocity script.
After this parsing, the only significant lines - the only ones that contribute to the functionality of a control - are
- #extend() statements
- property lines
- #method()...#end blocks
- #abstractMethod() statements
All other lines are quietly ignored.
10.2.3 Extends
|
Within a control file, the first part is an optional #extends statement.
This indicates that the control extends another control, named in the #extends.
For example, the physicalDatatypeBoolean has this line, to indicate that it extends the base physical data-type control.
#extends( physicalDatatype )
|
The detailed rules are:
- Unextended controls have no
#extends line.
- There can only be one
#extends line - a control file with two #extends will get a generate-time error.
- The word inside the
#extends can be as above -
just a word, to which the required ".control" extension is automatically added -
or a string literal (the control name inside quotes),
in which case the ".control" extension can be present but if it is not present it will be added.
The unquoted form is preferred.
By convention, make the #extends() line the first uncommented line of the control.
In generation systems, there is also a convention to make the name of the most basic (unextentded) control
derive from the key characteristic of the control - like physicalDatatype; extensions of that use the same name to start,
followed by the some specialisation - like physicalDatatypeBooleanPrimitive.
10.2.4 Properties
|
A control can have properties defined in Velocity. This follows the Java properties file format, i.e.
These follow the rules for component.properties
concerning ordering - the order of the properties lines is significant - and overriding.
Overriding of controls is an important topic and is covered in a later section.
10.2.5 Methods
|
The final part of the control is that it can have methods.
Methods can be defined in controls, following the normal rules for methods.
In addition, it it possible to declare that a method is required, but that it is not defined in this control.
This is equivalent to the Java "abstract" keyword for a method.
In JeeWiz, an abstract method is denoted by the #abstractMethod key giving the method name, plus any number of parameters:
#abstractMethod( putIntoSessionContext $key $object )
|
Note that the method name does not have a '$' but the parameters do.
An abstract method declaration makes the control abstract: it will not be possible to instantiate the control,
and any attempt to do so will get a runtime error.
An extension of the control will also be abstract, unless it (or one of its 'sub' controls) defines all abstract methods.
As you would expect, this is done by definining a method that matches in (case-sensitive) name and number of parameters.
The names of the parameters are not significant to the matching process - just the name and number of parameters.
A common approach is to make the most basic (i.e. the unextended) control list all the architected methods.
If it makes sense to provide a default implementation, then the basic control can define the method.
Otherwise, it can define the method as an abstractMethod, requiring sub-controls to define the method.
This pattern of usage makes controls similar to Java abstract classes rather than interfaces.
You can put '-' on the end of the abstract method name (e.g. #abstractMethod( instantiateRuntimeLoggerObject- ),
to document that it is expected to remove trailing whitespace.
However, this '-' is ignored: it is the #method declaration that determines whether trailing whitespace is removed.
10.2.6 Aggregating Properties And Methods
|
Like models objects, controls are extendable/customisable in two dimensions. To summarise
- The features of a control (i.e. properties and methods)
of a given name are constructed by aggregating across template directories,
with features defined in .controls at the top of the template directory stack overriding features of the same name from lower down.
The detail for methods was described previously;
the handling of properties is the same as for component.properties.
This gives us the functionality in the current build for a control of a given name - e.g. 'myControl' - unique to that name.
- Then the full functionality of a control is constructed by aggregating across the extensions.
The net result of this approach is that complete architectures can be built up by extending and overriding,
but individual features can be overridden by minimal files -
a ".control" file in a customer-specific template directory can have just one line defining an override for a property setting, for example.
Copyright (c) 2001-2008 New Technology/enterprise Ltd.
