= 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 1. Import statements 1. 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. {{{ }}} 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 {{{ }}} === Webservice Modules === * warfilename: the name of the warfile to generate. Optional * wsdl.dir: The directory containing the wsdl file. Optional Default values {{{ }}} 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: {{{}}} * Webservice interface modules: {{{}}} * Webservice Modules: {{{ }}} 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 {{{ }}} 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{{{ }}} * build.project.libs: The project libs to use when compiling, but not when packaging. Defaults to none{{{ }}} 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 {{{ }}} 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. 1. 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:''' {{{ }}} === 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. {{{ }}} == 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 {{{ }}}