JeeWiz Architect's Guide - Aggregating XML Files Into A Model


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 3. JeeWiz Input

3.2 Aggregating XML Files Into A Model

The previous section described the aspects of JeeWiz input files relevant to single file, single model builds. This section describes how JeeWiz can process multiple input files to construct a model, and how to use multiple models.

The issues to be addressed are

the specification may be large - it makes sense to break it up into multiple files
during development, it will be important to have work going on in parallel on different parts of the specification
some model objects must have a parent object to sensibly drive the build process.

3.2.1	The Assembly Directory
3.2.2	Non-Assembly XML Files in an Assembly Directory
3.2.3	Subdirectories

3.2.1 The Assembly Directory

In order to use multiple files, you must use the assembly directory approach, which means you must specify the the assembly directory via the 'assemblyDir' build property either by default (so assemblyDir=specification) or explicitly. In other words, you cannot specify the 'assemblyFile' build property: this overrides assemblyDir and restricts the build to a single file.

With the 'assemblyDir' approach, there must be a file named 'assembly.xml' in the assembly directory. This is the starting point for constructing a multi-file model.

The root element in the assembly directory's assembly.xml becomes the top-most element in the aggregate model. As you would expect, other elements in this file are nested underneath the top-most element in a hierarchical relationship mimicking the XML. For example, the nesting of a '<method>' element inside the '<session>' dictates that the method appears on the list of methods for the session.

3.2.2 Non-Assembly XML Files in an Assembly Directory

The first possibility for adding more XML files into the input model is to place them in the assembly directory.

We use the term non-assembly XML files to mean all files in a directory with '.xml' extension, other than assembly.xml. Note that this is case-sensitive, even on Windows: files will a '.XML' extension are not non-assembly XML files.

Such files placed in the assembly directory are considered to be JeeWiz specification files. There can be other types of file in a specification tree, but they are silently ignored by JeeWiz.

Non-assembly XML files must be well-formed XML files in their own right - they must have a root element. The non-assembly XML files in an assembly directory are incorporated into the aggregate model by nesting the root element in the non-assembly XML file under the root element of the assembly object. For example, say we have the following files and contents:

specification/assembly.xml <application name="ear1"/>
specification/Exception1.xml <jwclass name="Exception1"/>

The aggregated specification would be the same as if you had written it like this:

<application name="ear1">
<jwclass name="Exception1"/>
</application>

If you make quick backups of specification files under Windows by copying and pasting the files, they are named "Copy of ...". If these are interpreted as JeeWiz specification files, the build will be incorrect. To prevent this, by default, XML files with spaces in them are ignored. There is an 'allowSpacesInFiles' property that allows you to overrride this behaviour.

3.2.3 Subdirectories

The second facility for breaking up specifications is to use subdirectories.

For example, a very natural structure would be to have nested directories for

the applications
EJB Jars within the application
entities and sessions EJB jar/assembly.

When JeeWiz is run in assemblyDir mode (i.e. using multiple input files), it processes all subdirectories below the assembly directory, incorporating all XML files into the specification.

There are two rules for determining how the aggregation is done:

The root elements of assembly.xml files in subdirectories are nested underneath the root element of the nearest parent directory's assembly.xml file.
The root elements of non-assembly.xml files are nested underneath the root element of the assembly.xml file in (a) the same directory, if the subdirectory contains an assembly.xml file or (b) the nearest parent directory, if the subdirectory does not contain an assembly.xml.

The following example demonstrates these rules. It shows how the example specification from the previous section could be mapped onto XML files in a directory structure:

The example shows how the rules operate:

The ejb-jar is a nested element of the application element because ejb-jar is an assembly object (in Jar1/assembly.xml), which is nested in the next higher assembly object, which in this case is the application (defined in assembly.xml).
The account entity is nested inside the ejb-jar because it is defined in a non-assembly XML file (Jar1/account.xml), and it has an assembly file (Jar1/assembly.xml) in the same directory.
The accountHolder entity is nested inside the ejb-jar because it is defined in a non-assembly XML file (Jar1/Entities/holder.xml) with no assembly file in that directory, so the next higher assembly.xml file (Jar1/assembly.xml) is used as its parent.

The following additional points should be noted about this structure:

The names of the XML files themselves, other than the special name assembly.xml, does not affect the types of objects and names in the resulting aggregated specification. For example renaming Jar1/account.xml to Jar1/accountEntity.xml would have no effect on the resulting aggregate.xml and the two specifications would be identical as far as JeeWiz is concerned (as long as the renaming did not move the files alphabetical position in relation to other non-assembly files in the assembly-directory, which would change the order the elements from the files appeared in).
Intermediate directories can be used for convenience. We show entities being defined in the EJB jar directory and in a (non-assembly) subdirectory, but the entities both end up nested within the EJB jar.
The order in which nested elements appear in elements is
1. The nested elements in assembly.xml.
2. Nested elements from sub-directories, which are processed in alphabetical order.
3. Non-assembly XML files in the same directory.
For most types of build, this ordering is not important. For example, the J2EE application generation systems are not affected logically by the order of processed files. Of course, it will affect the order of generated code - for example, the order of methods and attributes in a Java class - but this does not change the logical structure of the code. Order is important in the documentation system, and you will have to use directory and file names to generate the order you want.