Custom Build Framework

In developing the Bitstorage subproject of DOMS, we created a rather elaborate build framework for handling interdependent webservices. Here is the documentation on how to use it.

Every module must have a build.xml. All build files have a specific structure

  1. Property definitions
  2. Import statements
  3. Set definitions

There are at present three kinds of modules

Property definitions

Every module build file must set the property global.dir to the correct value in regards to its basedir. This must happen as the firsts line of the project.     <property name="global.dir" value="${basedir}/../../.."/>

Every other property that should be set, must be set now, before any imports or something else is performed

Each of the kinds of module have specific properties that control how the build is performed

Common modules

Default values

    <property name="jarfile" value="${ant.project.name}.jar"/>
    <property name="srcpack.zip" value="${ant.project.name}-src.zip"/>

Webservice Modules

Default values

    <property name="warfilename" value="${ant.project.name}.war"/>

If wsdl.dir is not set, the webservice will be built without a wsdl. This is the expected behaivour for pure REST webservices.

Webservices inherit from Common, so all properties above are also respected.

Webservice Interface Modules

If generalSuperExceptionName is set, all generated exceptions will have this line inserted

    extends ${generalSuperExceptionName}

And all webservice method definitions that throws any exceptions will be specified to throw this

   throws ${generalSuperExceptionName}

This is nessesary to use the exceptionmapper functionality. Note that the generalSuperException is not generated, it must be provided, for example in the src folder of the module.

The properties from common modules also applies here.

Import statements

Then the nessesary imports should be performed. These depends on the kind of module

Set definitions

The set definitions override and control the build process.

Common modules

All of these are Optional.

Module dependencies are one of the magical things. Some understanding of how this works is required.

There are a few gotchas here

  1. If A depends on B which depends on C, then A must also explicitly depend on C to build. C will be build just because it is a dependency of B, but C will not be added to the classpath when building A.
  2. Even through dirsets allow a rich notation for specifying which dirs are selected, do not use it. The scripts that do the dependency handling are made in javascripts, and are not geared to exotic ant structures. Use this notation, and this notation only:

        <dirset  id="module.dependencies" dir="${global.dir}/modules/">
            <include name="webservice-common"/>
            <include name="characteriser/characteriser_interface"/>
        </dirset>

Webservice Interface Modules

Webservice Modules

    <dirset  id="module.dependencies" dir="${global.dir}/modules/">
        <include name="lowlevel/lowlevel_interface"/>
        <include name="webservice-common"/>
    </dirset>

Targets

There are, at present, defined 5 targets. These are all declared in build-common.xml but sometimes ammended in some of the other buildfiles. You should not declare you own targets in the module build file, unless you really know what you are doing.

Targets not on this list are just something that needs to be done during the build process, and should never be called by the user.

Webservice modules

For webservices, the dist target is ammended to depend on war, so you do not need to call war specifically.

Webservice Interfaces

Conclusion

Here is a complete build file for one of our modules

<project name="lowlevel_impl" basedir=".">

    <property name="global.dir" value="${basedir}/../../.."/>
    <property name="warfilename" value="lowlevelbitstorage.war"/>
    <property name="wsdl.dir"
                  value="${global.dir}/modules/lowlevel/lowlevel_interface/data/wsdl"/>

    <!--Contain the normal build tasks, including war-->
    <import  file="${global.dir}/build-webservice.xml"/>

    <!--Adds the soap libs to the build-->
    <import file="${global.dir}/build-soap-webservice.xml"/>

    <!--Adds the rest libs to the build-->
    <import file="${global.dir}/build-rest-webservice.xml"/>


    <dirset  id="module.dependencies" dir="${global.dir}/modules/">
        <include name="lowlevel/lowlevel_interface"/>
        <include name="webservice-common"/>
    </dirset>


    <!--Project libs used by this module-->
    <fileset id="project.libs" dir="${global.dir}/lib">
        <!--The following are only needed by surveilance-->
        <include name="doms-surveillance-rest-0.0.1/jars/**/*.jar"/>
        <include name="doms-surveillance-status-0.0.1/jars/**/*.jar"/>
    </fileset>


</project>

CustomBuildFramework (last edited 2010-03-17 13:09:22 by localhost)