Multi Module Projects (Version 1)

Note: The following applies to Enunciate version 1.x. For multi-module projects in Enunciate 2, see Multi Module Projects

Multi-Module Projects

Complex projects are usually managed by breaking the project into sub-projects, a.k.a. "modules". It often happens that the objects/classes that need to be exposed as part of a public Web service API reside in a different module than that of the Web service endpoint classes that expose them.

As of Enunciate 1.12, objects that are statically referenced by Web service endpoint classes are automatically discovered as part of the Web service API. Enunciate uses JAXB's definition of "statically referenced", including honoring the @XmlSeeAlso annotation on any endpoint class.

However, you'll quickly notice that any classes that reside in modules different from the module in which Enunciate has been invoked are missing the documentation on other goodies that you get when you invoke Enunciate directly on the Java source code. This is because only the compiled bytecode is supplied to Enunciate, and it can't leverage any information found in the original Java source code.

Importing API Classes

In order for Enunciate to leverage the additional goodies found in the original Java source code, you've got to provide Enunciate with additional information about these classes. This is referred to as "importing" API classes.

The process for importing API classes is fairly straightforward:

1. Specify which classes are to be imported.
2. Make the Java source code available on the classpath.

Specifying Import Classes

Classes to be imported are specified in the Enunciate configuration file with the api-import element. The api-import element takes an attribute, pattern that can be used to specify the classes to be imported. The pattern is an Ant-style pattern with '.' being the path separator character. Enunciate will scan the classpath and apply the pattern(s) to the fully-qualified name of the classes to determine which classes are to be imported.

Consider this example:

<enunciate ...>
  <api-import pattern="com.mycompany.pck1.dao.*" />
  <api-import pattern="com.mycompany.pck2.**" />
  <api-import pattern="com.mycompany.pck3.MyClass" />
  <api-import pattern="com.mycompany.pck3.MyClass.MyInnerClass" />
  ...
</enunciate>

This will tell Enunciate to import all classes in the com.mycompany.pck1.dao package, all classes in the com.mycompany.pck2 and any of its subpackages, the com.mycompany.pck3.MyClass class, and the com.mycompany.pck3.MyClass.MyInnerClass. Note that inner classes, for the purposes of applying the pattern, are considered as if they would be in the package named by their container class; if the pattern com.mycompany.pck3.MyClass.MyInnerClass were not specified, the com.mycompany.pck3.MyClass.MyInnerClass class would not be imported.

Note: In addition to classes imported via the configuration file, any classes that are "exported" (e.g. using the maven export goal) are also automatically imported. See "Exporting API Classes" below for details.

Making the Java Source Available

For all imported classes (and only for imported classes) Enunciate will also scan the classpath for an associated Java source file. If the Java source file exists on the classpath in the same place (i.e. same directory) where the compiled class would be expected, Enunciate will use the source file to generate the documentation instead of the compiled class.

Maven Users

Maven is especially suited to support multi-module Enunciate projects. For this example, consider a module named "domain" that contains classes that are to be imported into an Enunciate-supported war module named "webapp". In the pom.xml for the domain module, just leverage the maven-source-plugin to attach the source jar to the module:

<project ...>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-source-plugin</artifactId>
        <executions>
          <execution>
            <id>attach-sources</id>
            <phase>package</phase>
            <goals>
              <goal>jar</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

Exporting API Classes

Using the Enunciate configuration file is not the only way to import classes. Any classes that are "exported" will be automatically imported.

The export process is done by creating a file that consists of a newline-separated list of the exported classes that will be available on the Enunciate classpath at the entry META-INF/enunciate/api-exports. Enunciate will query for this file and add each of the exports to documentation.

Maven Support for Exporting Classes

For Maven users, there exists a Maven plugin that can be used to export API classes for later use in an Enunciate project. The plugin is for use with jar packaging and will add the enunciate/api-exports file to the META-INF directory of the created jar. Your classes will be brought through the standard Enunciate validation process.

Example

<project>
  ...
  <packaging>jar</packaging>
  ...

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.enunciate</groupId>
        <artifactId>maven-enunciate-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>export</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
  </build>

  ...
</project>

This will export all API classes in the created jar artifact so that any Enunciate project with a dependency on this artifact will automatically import those exported classes.