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

• Common modules, ie. those that just produce a jar
• Webservice Modules, ie. those that end up producing a war
• Webservice interface modules, ie. those that compile a wsdl to java code for a webservice module

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

• jarfile: the name of the jarfile to generate. Optional
• srcpack.zip: the name of the zipfile with the sources. Optional.

Default values

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

Webservice Modules

• warfilename: the name of the warfile to generate. Optional
• wsdl.dir: The directory containing the wsdl file. Optional

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

• wsdl.dir: The directory containing the wsdl file. Required
• wsdl.file: The location of the wsdl file itself. Not relative. Required.
• wsdl.package: The java package name of the generated classes. Required
• generalSuperExceptionName: The qualified name of a class to act as the superclass of all generated exception classed. Optional.

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

• Common modules: <import file="${global.dir}/build-common.xml"/>

• Webservice interface modules: <import file="${global.dir}/build-soap-webservice-interface.xml"/>

• Webservice Modules:

      <!--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"/>

  Of course, you only need to add the soap or the rest libs if you do not use both.

Set definitions

The set definitions override and control the build process.

Common modules

All of these are Optional.

• module.libs: The jars from the module lib folder to use. Defaults to all libs

      <fileset id="module.libs" dir="${basedir}/lib">
          <include name="**/jars/*.jar"/>
      </fileset>

  When building this jar, all these jars are copied to the dist folder.

• project.libs: The libs from the project lib folder to use. Defaults no none

      <fileset id="project.libs" dir="${global.dir}/lib">
          <exclude name="**"/>
      </fileset>

• build.project.libs: The project libs to use when compiling, but not when packaging. Defaults to none

      <fileset id="build.project.libs" dir="${global.dir}/lib">
          <exclude name="**"/>
      </fileset>

  The soap and rest libraries do not need to be added here, if you import the correct build-file as detailed above.

• module.dependencies: The other modules this module depends on. This is a Dirset, not fileset as the three previous. Default

      <dirset id="module.dependencies" dir="${global.dir}/modules">
          <exclude name="**"/>
      </dirset>

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

• Before building this module, the "dist" target is called in all the modules mentioned as dependencies. This can lead to further dependencies being called and so on. There is no protection against cyclic dependencies, so beware.
• While building this module, all jar files in the depended modules dist folder are present on the classpath. This includes the module libs from the dependent modules.

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

• No special Sets defined

Webservice Modules

• No special Sets defined. If they are soap webservices, they should depend on their interface module. These modules should depend on the webservice-common module, unless they know what they are doing.

    <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.

• clean: Cleans the module. Does not clean the dependencies, so beware.
• init: Initialise the module, create the needed temporary dirs
• compile: Compile the module, including building the dependencies
• jar: Package the module as a jar file in dist
• sourcezip: Package the module source as a zip file in dist
• dist: Make both jar and sourcezip, and copy the module libs to the dist folder.

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

• war: Packages the module as a deployable war file, including the specified libs and dependencies.

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

Webservice Interfaces

• There are a few additional targets, but these should not be called by the user.

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>