Skip to content

Executables

Jump to bottom Edit New page
Ryan Heaton edited this page Feb 28, 2024 · 44 revisions

Note: The following is applicable to Enunciate 2. For Enunciate 1.x executables, see Executables (Version 1).

Invoking Enunciate

Enunciate can be invoked in a variety of different ways:

See the Enunciate modules documentation for more information on how specific modules are configured and enabled.

Maven

The Enunciate Maven plugin is used to invoke Enunciate using Maven. There are actually two different Enunciate plugins available, the only difference between them being the modules that are included.

groupId artifactId modules included
com.webcohesion.enunciate enunciate-maven-plugin all modules
com.webcohesion.enunciate enunciate-slim-maven-plugin no modules

For each plugin, there are different goals available to run Enunciate: assemble and docs. The only effective difference between the two goals are the default configuration settings. The assemble goal is tailored for war packaging; the docs goal is used for other types of packaging and requires you to provide the docsDir. The docs goal can also be used in conjunction with the maven-site-plugin to integrate it into the project reporting.

Assemble Goal Example

The following example illustrates the assemble goal, presumably applied to a project with war packaging. It also illustrates how to include a custom Enunciate plugin.

<plugin>
  <groupId>com.webcohesion.enunciate</groupId>
  <artifactId>enunciate-maven-plugin</artifactId>
  <version>2.17.1</version>

  <configuration>
    ...
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>assemble</goal>
      </goals>
    </execution>
  </executions>
  <dependencies>
    <dependency>
      <groupId>com.mycompany.enunciate</groupId>
      <artifactId>custom-enunciate-module</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>
</plugin>

Docs Goal Example

<plugin>
  <groupId>com.webcohesion.enunciate</groupId>
  <artifactId>enunciate-maven-plugin</artifactId>
  <version>2.17.1</version>
  <executions>
    <execution>
      <goals>
        <goal>docs</goal>
      </goals>
      <configuration>
        <!-- the directory where to put the docs -->
        <docsDir>${project.build.directory}/docs</docsDir>
      </configuration>
    </execution>
  </executions>
</plugin>

Configuration

Note the following configuration parameters for each Maven plugin. Note also that any of these configuration options are overridden by the associated configuration elements in the configuration file.

parameter type description
configFile File The enunciate configuration file.
buildDir File The directory where Enunciate will put its output.
exportsDir File The destintation directory for exports. Defaults to the project build directory.
includes String[] List of api include patterns. Shortcut for the include pattern mechanism in the config.
excludes String[] List of api exclude patterns. Shortcut for the exclude pattern mechanism in the config.
projectExtensions String[] List of modules that should be included as "project extensions", meaning their generated output will be included in the Maven project, and in any IDEs that use the Maven project to define their own project structure.
exports Map The map of Enunciate artifacts to export. Map of artifact id to destination.
artifacts list of 'artifact' The list of artifacts to attach to the project. Each 'artifact' element supports a 'enunciateArtifactId', 'classifier', and 'artifactType'. This means that the enunciate artifact identified by 'enunciateArtifactId' will be attached to the project with as an artifact of type 'artifactType' and a classifier 'classifier'.
compilerArgs array List of additional arguments passed to Enunciate's Java compiler when compiling the project.
source String javac -source version parameter; defaults to the "source" of the maven-compiler-plugin.
target String javac -target version parameter; defaults to the "target" of the maven-compiler-plugin.
encoding String javac -encoding parameter; defaults to the encoding of the project.
sourcepathIncludes list of 'spec' The list of dependencies on which Enunciate should attempt to lookup their sources for inclusion in the source path. By default, dependencies with the same groupId as the current project will be included. Each 'spec' element supports a 'groupId' and an (optional) 'artifactId' element.
sourcepathExcludes list of 'spec' The list of dependencies on which Enunciate should NOT attempt to lookup their sources for inclusion in the source path. By default, dependencies with the same groupId as the current project will be included. Each 'spec' element supports a 'groupId' and an (optional) 'artifactId' element.
skipEnunciate boolean Hook to skip Enunciate documentation generation based on parameter. Also honored is the enunciate.skip global property.

Example

The following is a pom for the enunciate application. The Java XML client library jar (identified by artifact id "java.xml.client.library.binaries") is exported to "target/client.jar" during the "package" phase. Resources are copied and tests are run as usual with the Maven build lifecycle.

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany</groupId>
  <artifactId>myapp</artifactId>
  <packaging>war</packaging>
  <version>1.0</version>
  <name>My Application</name>

  <build>
    <plugins>
      <plugin>
        <groupId>com.webcohesion.enunciate</groupId>
        <artifactId>enunciate-maven-plugin</artifactId>
        <version>2.17.1</version>
        <configuration>
          <exports>
            <java.xml.client.library.binaries>client.jar</java.xml.client.library.binaries>
          </exports>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>assemble</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  <dependencies>
    ...
  </dependencies>
</project>

Gradle

There's a Gradle plugin available at com.webcohesion.enunciate:enunciate-gradle.

See the Enunciate Gradle Project for more information.

Ant

There's an Ant task available, com.webcohesion.enunciate.EnunciateTask. This task is an extension of a MatchingTask, so use the matching task functionality to select the source files on which to invoke Enunciate.

In order to set up the Enunciate classpath from Ant, you will need to know which modules are to be enabled when Enunciate is invoked. All jars necessary to support the Enunciate "base" modules are found in $ENUNCIATE_HOME/lib, where $ENUNCIATE_HOME is the path on the filesystem where the Enunciate distribution was unpacked.

Enunciate Task Attributes

Here's a table of the additional attributes:

attribute description required
basedir The base directory to scan for the source files to Enunciate. Yes
buildDir The directory where Enunciate will do it's work and put its output. Yes
configFile The Enunciate configuration file to use. No
classpathRef The reference to the classpath to use to Enunciate (used to find modules, invoke Javac, and copy jars for building the war). No; Defaults to the system classpath
javacSourceVersion javac -source version parameter No
javacTargetVersion javac -target version parameter No
compileDebugInfo Whether to compile with debug info. No; defaults to true.

Nested Elements

In addition to the nested elements of a MatchingTask that are used to select the source files on which to invoke Enunciate, the EnunciateTask supports additional nested elements.

  • The classpath element is a path-like structure used to specify the Enunciate classpath for execution.
  • The sourcepath element is a path-like structure used to specify the Enunciate sourcepath for execution.
  • The javacArgument element is used to configure extra argument(s) to apply when Enunciate compiles client-side artifacts. It supports an "argument" attribute to pass in the value of the argument.
  • The export element is used to specify an export. It requires a artifactId attribute, specifying the id of the artifact to export. It also requires a destination attribution, specifying the file or directory to which to export the artifact.

Example

The following example exports the documentation to "${docs.dir}", assuming "${enunciate.home}" refers to the enunciate home directory.

<path id="compile.classpath">
  <!--set up the classpath you need to compile your java source files-->
</path>

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

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

<enunciate basedir="src/main/java" buildDir="${enunciate.working.dir}">
  <include name="**/*.java"/>
  <classpath refid="compile.classpath"/>
  <export artifactId="docs" destination="${docs.dir}"/>
</enunciate>

Programmatic Interface

The programmatic entry point is com.webcohesion.enunciate.Enunciate. Just instantiate one of these, configure it as needed, and call execute().

Here's a summary of the configuration properties that might be worth using:

property description
buildDir The working directory where Enunciate will put its output files. There is no default; this property needs to be set.
modules The list of [[Enunciate modules
configuration The Enunciate configuration. This is a read-only property, but a file can be loaded using the loadConfiguration method.
exports The map of artifacts ids to files to which to export the artifacts generated by Enunciate.
sourceFiles The list of source files on which to invoke the compiler and the Enunciate engine. The default is an empty set.
classpath The classpath to use for the compiler used to invoke the Enunciate engine. The default is the empty set.
sourepath The sourepath to use for the compiler used to invoke the Enunciate engine. The default is the empty set.
compilerArgs The list of extra arguments to pass to the compiler used to invoke the Enunciate engine.
logger The logger to which Enunciate writes its messages.
includePatterns The list of patterns of classes to include with the Enunciate engine. The default is the empty set.
excludePatterns The list of patterns of classes to exclude from the Enunciate engine. The default is the empty set.

© 2023 Web Cohesion

Clone this wiki locally