DPML
Exporting Modules
HomeUtilitiesStationMetro
Exporting Modules
Tutorial Objective

In this tutorial we are demonstration how you can create a module artifact suitable for use by other third-parties.

index.xml

Our index definition remains unchanged except for the addition of a type production statement declaring that the module build produces a module artifact.

<?xml version="1.0" encoding="ISO-8859-1"?>
<index xmlns="dpml:library">

  <imports>
    <import uri="link:module:org/apache/ant"/>
    <import uri="link:module:dpml"/>
  </imports>

  <module name="org/acme" basedir=".">
  
    <types>
      <type id="module">
    </types>
  
    <project name="clock-api" basedir="api">
      <types>
        <type id="jar"/>
      </types>
    </project>
  
    <project name="clock-impl" basedir="impl">
      <types>
        <type id="jar"/>
      </types>
      <dependencies>
        <runtime>
          <include key="clock-api"/>
        </runtime>
        <test>
          <include ref="org/apache/ant/ant-junit"/>
          <include ref="dpml/transit/dpml-transit-main"/>
        </test>
      </dependencies>
    </project>

  </module>
  
</index>
The Generated Module Artifact

In this example we are building the module project using the Depot template. As such Depot's project aware tasks are detecting the type production statement associated with the module, resulting in the automatic production of the external module artifact under the target/deliverables/modules/acme-SNAPSHOT.module file.

<?xml version="1.0" encoding="ISO-8859-1"?>
<module name="org/acme" version="SNAPSHOT"
    xmlns="dpml:library">

  <types>
    <type id="module" version="1.0"/>
  </types>

  <resource name="clock-api" version="SNAPSHOT">
    <types>
      <type id="jar"/>
    </types>
  </resource>

  <resource name="clock-impl" version="SNAPSHOT">
    <types>
      <type id="jar"/>
    </types>
    <dependencies>
      <runtime>
        <include ref="org/acme/clock-api"/>
      </runtime>
    </dependencies>
  </resource>

</module>
Technical Note

The above module definition is not really ready for publication - after all it contains several references to SNAPSHOT versions (and we don't want to publish anything referrencing a generalized SNAPSHOT version). We can resolve this this using the -version option under the build command. For example, the following command will build the projects and module defintion using the version identifier 324.

$ build -version 324

The following module artifact demonstrates the impact of the -version option in terms of resource naming and the corresponding meta-data that is generated by the build process. All of the resources (jars, module files, etc.) are now suitable for publication into a public (or shared) repository.

<?xml version="1.0" encoding="ISO-8859-1"?>
<module name="org/acme" version="1.0.0"
    xmlns="dpml:library">

  <types>
    <type id="module" version="1.0"/>
  </types>

  <resource name="clock-api" version="324">
    <types>
      <type id="jar"/>
    </types>
  </resource>

  <resource name="clock-impl" version="324">
    <types>
      <type id="jar"/>
    </types>
    <dependencies>
      <runtime>
        <include ref="org/acme/clock-api"/>
      </runtime>
    </dependencies>
  </resource>

</module>
Summary

This tutorial has demonstrated the creation of a module artifact. During module generation our project defintions have been converted to simple resource defintions (involving the elimination of non-runtime concerns such as basedir, build and test dependencies, etc.). The remaining information is suitable for full transitive dependency evaluation by third parties (and associated model/name mapping to artifact uris). In the same way that we included the Ant module via an include staement - third-parties can now include the above information using something like:

<?xml version="1.0" encoding="ISO-8859-1"?>
<index xmlns="dpml:library">

  <imports>
    <import uri="link:module:org/acme#1.0"/>
  </imports>

  ...
    
</index>
Next Tutorial

Our next tutorial is also related to the capture and propergation of build-time meta-data. In the above example we have demonstrated how meta-data derived from module and project defintions can be transformed into artifacts that can be used by other projects. In our next tutorial we are going to focus on the capture and use of transitive dependency information related to runtime concerns.