MetaBoss Beginner's Guide

Description of the Ant build file

Overview

Index

project initialisation

A small number of Ant statements is located at the top of the file inside the <project> element, but outside of any <target> elements. These elements are project environment initiliasers. Because they are placed outside of any target element - they are always executed on startup irrespective of which particular target or targets are being executed:

• <typedef resource="taskdefs.xml"/>
  
  

  This standard Ant element plays very important role in plugging in MetaBoss cusom Ant targets into the project. When Ant encounters this element it will scan all jars at the classpath, find all files named taskdefs.xml and import all custom Ant task definitions from these files. So, instead of asking to define dozen or so MetaBoss custom tasks in every project, we only ask to include single ${metaboss_home}/lib/MetaBossAntIntegration.jar file in the Ant's classpath and place this simple Ant command somewhere at the top level in the project.

• <property name="debugbuild" value="true"/>
  
  

  This standard Ant element controls whether we run debug build or production build.

• <property environment="env"/>
  
  

  This standard Ant element imports all command shell environment variables into the project, so they can be referenced if desired.

• <property name="metaboss_home" location="${env.METABOSS_HOME}"/>
  <property name="build.dir" location="Build"/>
  <property name="release.dir" location="Release"/>
  <property name="designstudio.model.dir" location="Model/DesignStudio"/>
  
  

  These standard Ant elements define locations of four directories: 'metaboss_home' is the absolute path to the MetaBoss installation directory, 'build.dir' is the directory where temporary files produced during the build will be stored, 'release.dir' is the directory where release files produced during the build will be stored and 'designstudio.model.dir' is the directory where model files reside (the model files should be already there since we have completed modelling step).

build target

This is the default project target. It is executed when no target is specified when Ant is invoked. In our case this target forces full build of the example. This is definied via the list of targets this one depends on.

clean target

This target is used to delete all temporary files and directories. We use standard Ant <delete> task to do that. It is normally used prior to running of the full build to ensure that all files produced by build tools (eg. code generators, compilers etc) are created from scratch. The default build target described above does not depend on this one, so the 'clean' target has to be invoked explicitly if clean build is required.

init target

This target is used to prepare for the build. This involves setting up some build parameters, creating directories used in the build, etc. We use standard Ant <tstamp> and <mkdir> tasks to do that.

preparemodel target

In this step we are copying the model into the release area. This new copy will be our working copy (ie. the copy we conduct the build from). The reason we need to make another copy is that some MetaBoss utilities which we will run during the build will modify the model (this is not a bug, it is designed to work this way) and we would like to preserve the model file as it was entered by human.

The other outcome we are trying to achieve in this task is to produce the standard UML version of the model and store it using XMI format in the release directory. The standard XMI format is directly readable by many third party tools, so including the model in the release contributes to the openness of the software (by allowing consumers of the release to use model driven technologies to document, test or invoke the components in this release).

<ConvertMetaBossToMetaBoss destinationdir="${working.model.dir}"
                                 modeldir="${designstudio.model.dir}"/>
<ConvertMetaBossToUML umlfile="${release.dir}/docs/xmi/uml/AlmaMater.xmi"
                     modeldir="${designstudio.model.dir}"/>

As you can see in the fragment above, we use the special MetaBoss task to do the copying (rather than using Ant's standard copy task). This is because the MetaBoss specific task can also 'flatten' the model directory tree and store the whole model in one file. We also use the special MetaBoss task to do the export of the MetaBoss Enterprise Model. Both versions of the model are copied in the documentation area of the release, so people looking through documentation will notice these model files.

The 'modeldir' is the standard attribute used by MetaBoss utilities. It is used to specify path to the directory where the model is located.

updatemodel target

This target is used to run required MetaBoss Model Utilities over the AlmaMater model. MetaBoss Model Utilities are utilities which read and modify model itself (as opposed to Generators which read model and produce other files). In our case we run MetaBossStorageMetadataGenerator utility in order to add storage model definition into the model. We need Storage Model to define relational tables and constraints to be created in the database, however whole Storage Model can be derived completely automatically once the domain class diagram and brand of the database is known.

<MetaBossStorageMetadataGenerator ref="Enterprise/systems[CRS]/domains[Courses]"
    storagetechnologyref="Enterprise/technologyLibrary/storageTechnologies[MySQL]"
                modeldir="${working.model.dir}"/>

As you can see in the fragment above, we identfy required domain and storage technology by their unique references. Each element in MetaBoss model is identifiable by unique reference. This unique reference is the string with path-like expression derived from the element's ownership chain (ie. chain of owners from the top Enterprise element to the element being referenced). Please note that there is no need to manually reconstruct the reference from the model tree. MetaBoss DesignStudio always displays the reference of the element selected in the model tree in the 'Properties' tab at the bottom right corner of the screen.

The 'modeldir' attribute points to the directory where the model is.

buildmodules target

This target is used to build executable modules (jar files) straight from the model using special MetaBoss Builder utility. MetaBossBuilder is providing "model driven build" facility where developer only needs to nominate the types of modules required and the model elements which should be included in these modules. This approach is a little different (and we believe better) to the procedural approach where developer would need to define all steps in the build process one-by-one (eg. generate code, compile, create jar file etc). Do not worry if you find the rest of this paragraph a little hard to understand because it uses a lot of MetaBoss specific terms. Later on, once we have revied what we have built, things will hopefully become clearer.

The common attributes of the build applicable to all modules which are being built are specified as the attributes of the MetaBossBuilder task as follows:

<MetaBossBuilder modeldir="${working.model.dir}"
                      ref="Enterprise/systems[CRS]"
                   gendir="${build.dir}/generatedsource"
                 classdir="${build.dir}/classes"
                   libdir="${release.dir}/lib"
              implssrcdir="Source">

The 'modeldir' attribute points to the directory where the model is.

The 'ref' attribute contains the reference to the element which owns all the modules we are building. In our case it is the CRS system.

The 'gendir' attribute points to the directory where generated source files should be saved to.

The 'classdir' attribute points to the directory where compiled java class files should be saved to.

The 'libdir' attribute points to the directory where assembled modules (jars, ears, wars etc) should be saved to.

The 'implssrcdir' attribute points to the directory where handcoded source can be found (note that we do not have any handcoded source as of yet - we will add some later in the example).

Each module we need to build is defined in the distinct sub-element of the MetaBossBuilder task. In our case we will build following modules:

• <BusinessServicesInterfaceModule>
    <IncludeServiceAdapter type="generic.stringstructures"/> 
    <IncludeServiceAdapter type="generic.xmlstrings"/> 
    <IncludeServiceAdapter type="generic.simplifiedstringstructures"/> 
    <IncludeServiceAdapter type="generic.domelements"/> 
    <IncludeServiceProxy type="transactionmanagementproxy"/> 
  </BusinessServicesInterfaceModule>
  
  

  This module contains the "outermost" layer of the system - the interfaces to the Business Services. This is the only module we need to supply to client software developers at the development time. In other words this is the only module the external software needs to compile with. It has everything the client needs - interfaces to business services and classes representing value types used as input and output data.

  This module can also include various styles of Business Service Adapters specified in the <IncludeServiceAdapter> sub-element. Adapters are client side convenience classes designed to help with different styles of service invocation. For example 'generic.xmlstrings' helps to invoke services with XML documents used in input and output. The code for most of the adapter types is generated automatically.

  This module can also include various styles of Business Service Proxies specified in the <IncludeServiceProxy> sub-element. Proxies are "see through" classes designed to seamlessly plug in between the Business Service client and server. For example 'transactionmanagementproxy' is responsible for managing of transaction bracket around service invocation in a way when neither client nor server code need to worry about it (similar to what J2EE container does). The code for most of the proxy types is generated automatically.

• <BusinessServicesImplementationModule>
    <DomainSupportImplementation/>
    <GeneratedImplementation type="xmldevsimulator"/>
    <IncludeHandcodedImplementation type="impl"/>
  </BusinessServicesImplementationModule>
  
  

  This module contains implementations of the business services. It is is used on the server side of the Business Services. Some of the implementations are automatically generated, the others are handcoded and just included here.

  The <DomainSupportImplementation> element directs builder to generate and include in this module the implementation for the Domain Support Services - the services which offer basic Create/Read/Update/Delete operations for all entities in all domains.

  The <GeneratedImplementation> element directs builder to generate and include in this module the specified type of service implementation. In our case we are asking to include 'xmldevsimulator' implementation - the xml file driven business services simulator implementation.

  The <IncludeHandcodedImplementation> element directs builder to include in this module the specified handcoded implementation of the services. Later on in this example we will discuss how to create the handcoded implementation and where to locate it so this build process finds it.

• <BusinessDomainsImplementationModule>
    <IncludeStorageImplementation/>
  </BusinessDomainsImplementationModule>
  
  

  This module contains implementations of the domain business objects layer. The implementation classes are always generated from the model and do not require any handcoded additions. This module is used on the server side of the Business Services. By specifying <IncludeStorageImplementation> element we can force generation and packaging of the database dependent persistence layer inside this module.

maintenancescripts target

documentation target

This target contains instructions to generate documentation. We generate two types of documentation:

• MetaBoss specific 'metadoc' documentation. This is the html based documentation which is styled similarly to javadoc. However, the 'metadoc' is documenting model elements rather than java classes and interfaces. It is generated with use of generic MetaBossGenerator task with planName="documentation.metadoc". The result of generation will be placed in the ${release.dir}/docs/metadoc directory.

• Javadoc documentation. This is the html based documentation commonly used for documenting Java classes and interfaces. It is generated with use of standard <javadoc> Ant task.The result of generation will be placed in the ${release.dir}/docs/javadoc directory.

packagerelease target

This target is used to perform any additional release packaging tasks. In our case we need to copy generated database mainteance scripts to some place in the release directory. We use standard Ant <copy> task for that.