Multi Module Projects

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

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.

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 and other goodies that you get when you invoke Enunciate directly on the Java source code. This is because if only the compiled bytecode is supplied to Enunciate, and it can't leverage any information found in the original Java source code.

Providing a Source Path

In order for Enunciate to leverage the additional goodies found in the original Java source code, Enunciate needs to be provided with the source path for these classes. For more information about the source path, see javac: Searching for Types.

In addition to providing a correct source path, Enunciate needs to be configured to include the source files of the API classes. For more information, see Discovering Source Files.

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 provide the source jar with 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>

The enunciate-maven-plugin (see Executables) will, by default, search for the source jars of all dependencies that are in the same groupId as the current module. You can configure this behavior in the enunciate-maven-plugin by using the sourcepath-includes and sourcepath-excludes plugin configuration options:

<plugin>
  <groupId>com.webcohesion.enunciate</groupId>
  <artifactId>enunciate-maven-plugin</artifactId>
  <version>${enunciate.version}</version>
  <executions>
    <execution>
      <id>assemble</id>
      <goals>
        <goal>assemble</goal>
      </goals>
      <configuration>
        <sourcepath-includes>
          <include>
            <!-- configure Enunciate to look for the source jars for all dependencies in the "com.mycompany.domain" groupId.-->
            <groupId>com.mycompany.domain</groupId>
          </include>
        </sourcepath-includes>
        <sourcepath-excludes>
          <exclude>
            <!-- but exclude com.mycompany.domain:domain-utils -->
            <groupId>com.mycompany.domain</groupId>
            <artifactId>domain-utils</artifactId>
          </exclude>
        </sourcepath-excludes>
      </configuration>
    </execution>
  </executions>
</plugin>

Ant Users

Ant users can provide the sourcepath to Enunciate using the sourcepath element:

<path id="enunciate.classpath">
  <fileset dir="${enunciate.home}/lib">
    <include name="*.jar"/>
    <exclude name="*-sources.jar"/>
  </fileset>
</path>

<path id="enunciate.sourcepath">
  <fileset dir="${enunciate.home}/lib">
    <include name="*-sources.jar"/>
  </fileset>
</path>

<taskdef name="enunciate" classname="com.webcohesion.enunciate.EnunciateTask">
  <classpath refid="enunciate.classpath"/>
</taskdef>

<enunciate basedir="src/main/java">
  <include name="**/*.java"/>
  <classpath refid="enunciate.classpath"/>
  <sourcepath refid="enunciate.sourcepath"/>
  <export artifactId="docs" destination="${docs.dir}"/>
  <javacArgument argument="-g"/>
</enunciate>