JeeWiz Architect's Guide - JeeWiz Input


	The Model-Driven System Builder

JeeWiz Architect's Guide

Contents > 2. Overview

2.2 JeeWiz Input - Simple XML

JeeWiz uses a simple form of XML as its "input model", which we refer to as the "specification".

The original source of a specification is a usually a UML model. However, we stress that any well-formed XML document can be used as the input to JeeWiz.

2.2.1	Input Model Transformations
2.2.2	Simple XML - The Bare Essentials
2.2.3	JeeWiz Format For Design Transforms
2.2.4	Aggregating Multiple XML Files
2.2.5	XML Pre-processing

2.2.1 Input Model Transformations

Models can be created directly in XML, either using a text editor or an XML editing tool. However, most models will be created by modeling tools, such as UML modelers (or possibly Microsoft Visual Studio Domain-Specific Language (DSL) designers in future).

Modeling tools create outputs in their own format, such as XMI (the OMG's XML Metadata Interchange format). To use such models with JeeWiz, a conversion to the JeeWiz format must be run. Conversions for a range of UML modeling tools are provided; see the Modeler's Guide for more information. Import from JavaDoc is also possible, although deprecated in version 3.8. It is quick to build imports for other formats that are, or can be, in XML format.

Note that we use JeeWiz itself to do the XMI transforms. A common alternative is XSL-T to do implement this sort of transform. In fact, the original transforms in the JeeWiz product were written in XSL-T. It turns out that the XSL-T transform is both very complicated to write and very slow to run. The XSL-T transforms in JeeWiz became unworkable when it started taking many minutes to transform medium-sized models. By using JeeWiz, the transforms are much simpler and take a few seconds.
By using a common simple XML format, JeeWiz can support many modelling formats. Supporting multiple input formats is important to JeeWiz for two reasons:

The large-scale transformations in JeeWiz are a significant capital investment. By supporting multiple modeling tools this investment can be spread across a wider market.
It is easier to write the large-scale transforms from a very simple format.

2.2.2 Simple XML - The Bare Essentials

We use the term 'simple XML' to indicate that JeeWiz XML is as simple as possible. The most important way in which simple XML differs from XMI or other modeling regimes is that it allows the specifcation to be stripped down to the bare essentials, removing all 'self-describing' features and defaults.

For example, here is the definition of an association 'end' in Rational Rose XMI:

<UML:AssociationEnd xmi.id = 'G.8' xmi.uuid = '3FF97E3A023D' 
  name = '' visibility = 'public' isSpecification = 'false' 
  isNavigable = 'true' ordering = 'unordered' aggregation = 'none' 
  targetScope = 'instance' changeability = 'changeable' 
  type = 'S.011.1755.16.22' >
  <UML:AssociationEnd.multiplicity>
    <UML:Multiplicity >
      <UML:Multiplicity.range>
        <UML:MultiplicityRange xmi.id = 'id.0121755.5' 
          lower = '0' upper = '-1' />
      </UML:Multiplicity.range>
    </UML:Multiplicity>
  </UML:AssociationEnd.multiplicity>
</UML:AssociationEnd>

and its conversion to JeeWiz format:

<end            uid="3FF97E3A023D"
                entity="Operation"
                multiplicity="Many"
                >

In the 'Simple XML' approach we do the following to avoid complexity:

Omit defaulted items - only specify the variations. This makes it quick and easy to create simple specifications.
Avoid unnecessary 'fluff', like the sequence of elements describing the multiplicity above. This sequence adds no value for the pragmatic users of UML or the consumers of XMI, but it adds to the complexity of creating or debugging XMI.
Use names (e.g. entity="Operation") rather than ID's (type = 'S.011.1755.16.22') to reference related elements. This makes it easier to create and debug simple XML.
Use attributes for items of information rather than nested elements, as early XML did.
Treat tagged values the same as other attributes - just make them attributes of the meta-classes they apply to.
Avoid namespaces and qualifiers on elements. For logical modeling they are not necessary and counterproductive - using qualifiers usually ties a modeling object to a physical concept.

Note that the above approach does not lose any information; rather, the important information is preserved and highlighted.

The way to create simple XML is as follows:

Use elements with names that directly express the modeling concepts - like '<entity>' or '<attribute>'.
Use attributes to express the properties of modeled objects.
Express lists of children by nesting XML elements.
Where references between elements are needed, use the names of objects (as in 'entity="Operation"' above).

Here is a fragment that expresses most of these ideas:

<entity            name="Customer">
  <attribute       name="CustomerID"
                   type="int"
                   />
  <attribute       name="name"
                   required="true"
                   />
</entity>

Typically the content of the XML (rather than the style of use) is defined by meta-models, which are discussed later. However, this is not required - it is possible to create models/specifications in a free-format way, unconstrained by a meta-model.

2.2.3 JeeWiz Format For Design Transforms

The JeeWiz 'Simple XML' format is an approach to using XML that aims to be as simple as possible. It turns out that this makes it a very convenient intermediate format for transforming design information.

The issue with transforming design information is that the structure of most formats is complex, particularly the variants of XMI and WSDL/XML Schema. Using the JeeWiz format as an intermediate format has two big advantages over converting directly between the complex formats:

Modularity. By going to a very simple format, the problem is broken down into two separate parts. Our experience of doing these transforms is that this makes the problem very much easier.
Design information typically gets used in many ways - typically involving transforms between formats. It is much easier to do this if the starting point is a simple format. The alternative is to use the complicated format and interpret it every time.

There are no restrictions on the use of the XML formats of JeeWiz, so development teams are free to use them for design transforms.

2.2.4 Aggregating Multiple XML Files

The input model normally consists of a single XML file. More advanced facilities discussed later are available for

model composition - splitting up models into multiple files across multiple directories and letting JeeWiz aggregate them to create on model
reading additional models as well as the main input models - effectively creating a tree of models. See the 'addSpec' feature of the build properties file

2.2.5 XML Pre-processing

There is one detail we need to mention here. Some XML-writing conventions use a '-' for element tags (element names) or attributes. We eventually want to reference these in the Velocity scripts, but '-' cannot be used in names in Velocity - it is a name terminator. So JeeWiz has a convention that XML element or attribute names are made available via Velocity with the '-' removed and the following letter capitalised. For example the name for a Java reference type can be specified in XML using

reference-type

but it is made available to Velocity as

referenceType