6.4 Engine Configuration Values

This section describes in detail the engine configuration values.

These values must be defined in the initial phase of configuration reading that establishes the model, additional specifications and rendering structure for the build. In other words, they must be defined by:

• Properties in the calling Ant task.
• Properties in one of the build properties files.

When you install JeeWiz (or you local support group configures it for you), it is possible to set up default values for these items so it is not necessary for modellers or programmers to know the configuration required. However, some situations require on of the build properties files to be set. For this reason, most of the J2EE examples do not have a build properties file.

Here is a fairly typical build properties file copied from a J2EE example:

# for WLS6 use the following line as 'model' model=weblogic6 templateDir=${jwhome}/resources/${model}/control assemblyDir=specification # no additional specs 'addSpec'...

The rules for the JeeWiz properties files are defined in the Property Files section.

Properties are a mixture of JeeWiz-defined global names and other names as required by the type of model being compiled.

The JeeWiz global properties, which are mostly defined in the Build Properties file, are:

addSpec*

Optional. This feature allows up to 10 additional specifications to be added to the build, using properties names addSpec, addSpec1, addSpec2, ... addSpec9. These specifications can be referenced by patterns and templates code in the main model to produce output based on the additional information.

The main specification drives the rendering process - it is the one that is built via patterns and Ant build.xml scripts. The additional specifications provide additional information that is required. For example, a common usage for this is to add a "filter" file, that can be used to add, remove or edit nodes in the main build.

Additional specifications take two forms. The simplest and most common is where the added specification is just an XML file, which is signalled by a file ending in anything other than '.jwp' (case-insensitive). All that is important in this case is the textual data in the XML file, so there is no need to read in a meta-model or extra configuration information behind the file. In this case, the XML file is read in as though it were an 'any' model with no additional properties.

Alternatively, the additional specification is a '.jwp' file - ending in '.jwp', case-insensitive. In this case, the addSpec file has exactly the same structure as the main '.jwp' file:

• a template directory ('templateDir' property) and either the assemblyFile or assemblyDir must be specified;
• other properties can be specified in the file as well.

The syntax for the two styles of specifying an additional specification is

addSpec[n]=[optionalName:]filename.xxx[,doPatterns][,doValidation] addSpec[n]=[optionalName:]filename.jwp[,doPatterns][,doValidation]

The 'xxx' on the end of 'filename.xxx' indicates that any extension, except '.jwp', is valid. The 'optionalName' defines the name used, in the main specification's rendering, to access the root node of the additional specification (e.g. using '${optionalName}', or $optionalName in Velocity). If the optionalName is omitted, then the addSpec* name is used.

For example, the J2EE meta-model build uses the screen's meta-model using a parent chain:

addSpec=parent:../screen/build.jwp

This defines the file '../screen/build.jwp' as the additional specifications build properties file, with the '..' being interpreted relative the the current (build properties) directory. The assembly file or directory specified in screen/build.jwp is read in using the template directory specified in the build.jwp file. The 'optionalName' in this case is 'parent', so a 'parent' property is added to the main build's top component. If the 'parent:' had been omitted ('addSpec=../screen/build.jwp') then the 'addSpec' property would have been added to the main build's top component.

Note that it is allowed, and useful, to have recursion within addSpec's. This is only available when a 'jwp' addSpec file is used, and then it is possible to have one or more 'addSpec' lines in the addSpec file. For example, the screen's build.jwp file referred to above (which is available in the file jeewiz/resources/screen/build.jwp) has the line

addSpec=parent:../bizobject/build.jwp

In other words, the parent of J2EE is the screen meta-model, and its parent is the 'bizobject' meta-model. In this case, the added 'bizobject' specification is referenced via the parent property on the root node of the screen's additional specification. This means that, in general, it is possible to add a whole tree of additional specifications.

allowSpacesInFiles

Optional, defaults to false. If set to true (case-sensitive), allows spaces in specification filenames - i.e. XML files in the assemblyDir or subdirectories. By default, files with spaces are ignored when building the model, so you can have backup *.xml files in the same directory ("Copy of ..." in Windows).

assemblyDir

Required unless assemblyFile is specified. The 'main specification' directory, with assembly.xml and optionally other *.xml files in the same directory or sub-directories. The specification gives values to elements and attributes allowed by the model - e.g. '<application  name="helloJWorld">' to describe an application in the J2EE model. By convention, the assemblyDir is specification; this is also the value set in ${jwhome}/bin/build.properties'. The root element in ${assemblyDir}/assembly.xml becomes the root of the specification.

assemblyFile

Required. Specify 'assemblyFile' when you want to use a single named file for the specifiation. The value of this property must be the name of the single file to use, and it must exist. If you specify assemblyFile, any value specified for 'assemblyDir' is ignored.

The single-file build is particularly useful if you have a pipeline of JeeWiz builds; it then allows you to avoid having to set up a specification directory just for the single file.

copyElementTag

Optional. If set, the value overrides the 'copy' tag, to become the tag for copying elements. See the section on the copy feature for more details. This property is only relevant if 'useCopy' (defined above) is also set.

copyIdAttributeName

Optional. If set, the value overrides the 'id' attribute, to identify an element for copying. See the section on the copy feature for more details. This property is only relevant if 'useCopy' (defined above) is also set.

copyRefAttributeName

Optional. If set, the value overrides the 'ref' attribute, to refer to an element to be copied. See the section on the copy feature for more details. This property is only relevant if 'useCopy' (defined above) is also set.

discardLeadingTabs

Optional, defaults to true. If set to false (case-sensitive), causes leading tabs in Velocity scripts to be included in the output; normally they are discarded.

For all the JeeWiz-supplied models, this should be set to true - if you care about the structure of the generated code or text.

The standards for leading tabbing used in the more complex JeeWiz-supplied scripts are:

• Indent each nested Velocity directive one tab for each nesting
• Indent basic output (code, XML files) 5 tabs and then indent from there.

The problem this is addressing is the complexity of understanding two concurrent nesting regimes - Velocity macros and the produced code. These standards make it possible to see the outline of the block structure of both simultaneously. See the RemoteDelegate.inc script for an example of a reasonably complex example where discarding tabs makes it much easier to understand the structure.

This is a global property, and actioned by the JeeWiz task, so it must be set in one of the 'build.properties', or '.jwp' files. It will not be recognised if set in a system.properties file.

doPatterns

Optional, defaults to 'true'.

If set true, this flag causes JeeWiz to run patterns and validation - which is normally what is desired. The option of setting 'doPatterns' to true and avoid running patterns and validations is useful in cases where the unembellished input is desired, such as in transforming models between various formats.

doValidation

Optional, defaults to 'true'.

This flag causes validation to be run - or rather, setting it false disables validation for the complete tree..

It is only relevant if 'doPatterns' is true: if 'doPatterns' is false, then validation is never run because it is part of the overall pattern processing.

There is also a doValidation property on all meta-classes that disables validation for that particular object.

dump

Optional, defaults to none - no dump.  When features which alter the input XML - like 'convert' and patterns - are used, it can difficult to determine exactly what XML is being used for the build.

Furthermore, with long sets of interconnected patterns and templates, it can be difficult to work through the calling hierarchy to see where a particular item is done. You can get information to help with both of the above problems by using the 'dump' facility which gives

• the exact XML being used by the build after all patterns have been processed
• a calling hierarchy for patterns and templates, by object processed and the starting file
• a log of the objects that fire patterns and the top-level objects the patterns create
• a list of the component types that have methods, the names of the methods defined on them, and the location of the component.methods file.

The format for this feature is 'dump=filename', as in the following, which will write the file to 'aggregate.xml':

ant "-Dpass=-Ddump=aggregate.xml"

You can restrict the dump to be only the XML after the patterns have been processed by defining the property 'dumpXmlOnly' (i.e. '-pass3=-DdumpXmlOnly' on the invocation of Ant via one of the example build.xml files). The quotes around the parameter are necessary because Ant incorrectly parses the property setting without them.

By default the indentation of attributes in the XML is 36 characters (i.e. property name starts in column 37). If you want to alter this, use the 'dumpIndent=' parameter followed by a number, as in:

ant "-Dpass=-Ddump=aggregate.xml" "-Dpass2=-DdumpIndent=40"

Note that the XML dump feature is also available for objects other than the root node via '.xmlDump', which calls down to the getXmlDump() method. In other words, if $dv is a dataview model object that you want to dump, you can say

$this.log( "data-view = $dv.xmlDump" )

This will dump all original and set (via setX()) values in the model object $dv, plus all nested XML elements and their set attributes.

extraClasspath

Optional. Specify here a classpath string holding any extra directories you need to compile any generated code. This is for your environment only. There are other jars that will be pulled in automatically from template (model) directories. To separate directories you can use either ';' or ':'; however, you must use '/' rather than '\' (this being a UNIX-style properties file).

Note that this is used in the model building process i.e. in the first stage jeewiz process and not in the second stage application building process. To add extra classpaths in the application build process see the Other facilties section in Interface To jwrun.xml

inputEncoding

Optional. This specifies the encoding of meta-programs (Velocity rendering files). It is also used as the default for reading files as strings or lines. The value must be the name of one of the Java character encoding schemes. The default is the default encoding for the current JVM (i.e. Charset.defaultCharset().name()).

outputEncoding

Optional. This specifies the default encoding of files written by templates. It is also used as the default for writing files. The default is the default encoding for the current JVM (i.e. Charset.defaultCharset().name()). The encoding of output files can also be changed on a file-by-file basis: see the 'outputEncoding' parameter on the Velocity task.

processPrefixes

Optional. By default, this is true and prefixes on elements and attributes are processed. If reset by specifying the value 'false', no prefix processing is done on elements and attributes, which means that

• prefixed elements and attribute names will come through as specified in the XML (e.g. "xmlns:xsd")
• no special handling of namespaces and the 'xmlns' prefix is done.

Because of the last point, this option should not be reset for XML Schema processing. In fact, there are only two situations when it makes sense to turn off prefix processing:

1. the XML is being processed as text rather than its meaning being interpreted, with a view to outputting some of the original prefixes (e.g. for dumping out the structure in a standard format, or to implement an XML merge).
2. there are XML elements that have different prefixes but the same unqualified name - <a:elt> and <b:elt>. It is almost never necessary to worry about this. We have done a lot of XML transforms and never yet had to worry about element name collisions across schemas.

The setting of the "processPrefixes" does not affect the lookup name for properties, templates and patterns. For example, the RsaRsm models have a root model object tag of <xmi:XMI> and the corresponding resource is <x-m-i> (which is our XML-style name for XMI) - it's not <xmiXMI> or some other function of the two 'xmi's.

singletonListsToProperties

Optional, defaults to true. By default, this allows the only nested element in a singleton list to be accessed using the name of the nested element as a property; see here for details. Set this false to disable this features.

strictXMLReadIn

Optional, defaults to false. If set to true (case-sensitive), this prevents 'extra' elements and attributes (i.e. those that are not defined in the meta-model) from being read into the XML.

templateDir

Required. The directory, or list of directories, defining the meta-classes and rendering to use.

Normally, this is a single directory, in which case it must reference a directory with a "model.properties" file and the remainder of the chain is specified by following the 'parent' property through the model.properties file(s). Alternatively, it can be a list of template directories separated by the path separator (i.e. ':' on UNIX, ';' on DOS) or ','; if this format is used, then the templateDir property specifies the complete list of template directories to use and the model.properties 'parent' property is not used to discover further template directories.

For JeeWiz-defined renderings, this will follow the pattern of ${jwhome}/resources/*/control - all renderings are stored under the resources directory, and the directory holding the compiled meta-models and the templates and patterns comprising the renderings is 'control'.

More details on the 'templateDir' are given here, and on the contents of template directories here section.

trace

Optional, defaults to 'false'.

If set true, this traces both templates and patterns. In other words, it is equivalent to setting both traceTemplates and tracePatterns.

traceExecution

Optional, defaults to 'false'.

If set true, this flag causes JeeWiz to start all scripts executed in trace mode. Note that the catch-all 'trace' flag described previously does not set this flag.

traceTemplates

Optional, defaults to 'false'.

If set true, this flag causes JeeWiz to log, in each generated file, all the source templates that were involved in generating the file. The log takes the form of a comment in the generated file's syntax (currently, Java, XML and JSP are supported).

This feature is particularly useful when multiples templates are involved in creating various parts of a generated file. In that case, each part is marked with the appropriate comment and the generated part is indented. By following the indentation, it is possible to see the calling structure of the generation sequence.

tracePatterns

Optional, defaults to 'false'.

If set true, this flag causes JeeWiz to mark model objects that are created by pattern with the path (in the format of the current platform) of the pattern file that created the object. This is done by adding a sourcePattern attribute, whose value is the source file. For example:

<interface   name="CarRentalProxy"
             access="public"
             package="jeewiz.test"
             sourcePattern="C:\...\classic-client\control\service\includeSpec.vm"
             >

Although you can log the sourcePattern or access it in other ways, the easiest way to see this information is to dump the XML, using the dump feature. You then see the layout given above.

If a pattern uses #parse to invoke other patterns, it is currently not possible to determine which #parse'd file created the model object. However, the aggregate XML dump (from the dump feature) also dumps the calling hierarchy of patterns at the end. This means to get further information on the source pattern, you can go to the end of the dump and search for the pattern file.

For example, the entry in the calling hierarchy dump for the source pattern in the example above looks (roughly) like this:

service  includeSpec.vm                  --\client\--includeSpec.vm
           SvcConsumer.inc               --\client\--SvcConsumer.inc
           SvcConsumerImpl.inc           --\client\--SvcConsumerImpl.inc
              SvcConsumerImplSpecial.inc    --\j2ee\--SvcConsumerImplSpecial.inc
           SvcProxy.inc                  --\client\--SvcProxy.inc
           SvcProxyImpl.inc              --\client\--SvcProxyImpl.inc
              SvcProxyImplSpecial.inc       --\j2ee\--SvcProxyImplSpecial.inc
           SvcConstants.inc              --\common\--SvcConstants.inc
           MessageExceptions.inc         --\common\--MessageExceptions.inc

The format of these entries is: meta-class ('service'), filename, and fully-qualified filename. Note that the fully-qualified directory has been abbreviated in the example to make it easier to see the calling hierarchy.

This example shows that the includeSpec.vm pattern for the 'service' actually comes from the 'client' includeSpec.vm. It then calls six different included patterns, for the ServiceConsumer, ServiceConsumer implementation etc. The implementation files have further call-outs to special code for the J2EE environment.

The use of the 'tracePatterns' (and, by extension, 'trace') build properties is a used as a quick-start approach for the early lifecycle of the set of patterns in a rendering. When the rendering matures or becomes more complex, the most convenient approach is to use the sourcePattern feature for manually marking which nodes are to have their sourcePattern set, and then not use 'trace' or 'tracePatterns' (but possible to use 'traceTemplates').

useCopy

Optional. If set by specifying the value 'true', the copy feature is enabled. The default is that the copy feature is disabled.

xmlDeclaration

Optional. If set, this string becomes the XML declaration in generated patterns. This is added to patterns automatically so that the pattern writer does not have to bother with it. However, it is not added to templates automatically, because it would be inappropriate for non-XML outputs.

xmlDeclaration is required if a non-default encoding is used. Examples of typical values for the xmlDeclaration are

<?xml version="1.0" encoding='UTF-8'?> <?xml version="1.0" encoding='UTF-16'?> <?xml version="1.0" encoding='ISO-8859-1'?> <?xml version="1.0" encoding='ISO-8859-2'?> <?xml version="1.0" encoding='ISO-2022-JP'?> <?xml version="1.0" encoding='Shift_JIS'?> <?xml version="1.0" encoding='EUC-JP'?>

By default, JeeWiz uses UTF-8.

The value of 'xmlDeclaration' is also copied into the properties of the Ant project that runs JeeWiz. This means it can be used (via '$xmlDeclaration') in templates that generate XML; it can also be overridden by entries in system.properties and component.properties entries.

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