Invoking Enunciate
Enunciate can be invoked in a variety of different ways:
A set of source files to be enunciated is always required. While invoking Enunciate without any options is valid, doing so will probably not get you the result that you want because Enunciate won't know where to put its artifacts, defaulting to an unspecified temporary location. So make sure you specify an artifact to export or a specific location to which to build.
Each module exports its own set of artifacts. Here's a quick reference to the available artifacts. Refer to the module documentation to find more details on what each module does. Most often, it's the fully-packaged war exported by the spring app module, so you'll want to export the artifact identified by the id "spring.war.file".
Maven
The Maven 2 Enunciate plugin is used to invoke Enunciate in the context of a Maven 2 POM. The groupId of the artifact is "org.codehaus.enunciate" and the artifact is "maven-enunciate-plugin". There are actually two ways to use the Maven Enunciate plugin. The first is by attaching a standard goal named "assemble" to a phase in the build lifecycle. The second is by simply leveraging the "enunciate-app" packaging. Both methods provide the same result. The former is for use with the Maven "war" packaging and leverages the Maven War plugin to package up the war. The latter uses Enunciate's internal mechanisms to build and package the war.
Classpath Setup
Maven users should already be aware that there are (at least) two different classpaths that are in play when invoking a Maven plugin: the plugin classpath and the project dependency classpath. The Maven Enunciate plugin already establishes its own plugin classpath, and this should rarely, if ever, have to be manipulated. However, the project dependency classpath defines the libraries that are to be used to compile and run the application.
Enunciate provides a top-level runtime ("rt") POM that can be conveniently included in the project dependencies of an Enunciate project. The groupId is "org.codehaus.enunciate" and the artifactId is "enunciate-rt". This is used to include the core libraries needed at runtime to drive the Enunciate application, including the Jersey runtime, the XFire runtime, the Spring application runtime, etc. As of version 1.9, there are alternatives to the XFire runtime: JAX-WS RI and CXF. If either of these modules are enabled, you will want to exclude the XFire runtime ("org.codehaus.enunciate:xfire-rt") and include the runtimes of these modules ("org.codehaus.enunciate:jaxws-ri-rt" and "org.codehaus.enunciate:cxf-rt" respectively).
Configuration
Note the following configuration parameters:
| parameter | type | description |
|---|---|---|
| configFile | File | The enunciate configuration file. |
| generateDir | File | The directory to use for the "generate" step. The default is "${project.build.directory}/enunciate-generate" to make it available for IDEs. |
| compileDir | File | The directory to use for the "compile" step. |
| buildDir | File | The directory to use for the "build" step. |
| packageDir | File | The directory to use for the "package" step. |
| scratchDir | File | A directory Enunciate can use as a scratch directory. |
| outputDir | 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. |
| 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 'enunciateArtifatId' will be attached to the project with as an artifact of type 'artifactType' and a classifier 'classifier'. |
| addGWTSources | boolean | Whether the gwt source files (generated client-side classes and apps) should be added to the compile source roots of the project. This is useful for the IDE plugins. Default: true. |
| addActionscriptSources | boolean | Whether the actionscript source files (generated client-side classes and services) should be added to the compile source roots of the project. This is useful for the IDE plugins. Default: true. |
| addXFireClientSourcesToTestClasspath | boolean | Whether to add the generated XFire client-side code to the test classpath (for testing purposes). Default: false. |
| addJAXWSClientSourcesToTestClasspath | boolean | Whether to add the generated JAX-WS client-side code to the test classpath (for testing purposes). Default: false. |
| gwtHome | String | The path to the GWT home directory, in case you're developing GWT applications. |
| flexHome | String | The path to the Flex home directory, in case you're developing Flex applications. |
| compileDebug | boolean | Whether to compile with debug information. |
| warArtifactId | String | (For use only with "enunciate-app" packaging.) The id of the Enunciate artifact that is to be the primary Maven 2 artifact. Default: "spring.war.file". |
| warArtifactName | String | (For use only with "enunciate-app" packaging.) The name of the primary Maven 2 artifact. Defaults to the name of the Maven 2 project. |
| warArtifactClassifier | String | (For use only with "enunciate-app" packaging.) The name of the classifier for the primary Maven 2 artifact (no default supplied). |
Example
The following is a pom for the enunciate application. The enunciate configuration file is located at "path/to/enunciate.xml" relative to the pom directory. The JDK 1.4 client library jar (identified by artifact id "client.jdk14.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.ifyouwannabecool.war</groupId>
<artifactId>ifyouwannabecool</artifactId>
<packaging>war</packaging>
<version>1.12</version>
<name>ifyouwannabecool</name>
<url>http://www.ifyouwannabecool.com</url>
<build>
<plugins>
<plugin>
<groupId>org.codehaus.enunciate</groupId>
<artifactId>maven-enunciate-plugin</artifactId>
<configuration>
<configFile>enunciate.xml</configFile>
<exports>
<client.jdk14.library.binaries>client.jar</client.jdk14.library.binaries>
</exports>
</configuration>
<executions>
<execution>
<goals>
<goal>assemble</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.5</source>
<target>1.5</target>
</configuration>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>org.codehaus.enunciate</groupId>
<artifactId>enunciate-rt</artifactId>
<version>1.12</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
Ant
There's an Ant task available, org.codehaus.enunciate.main.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.
Defining the Enunciate Classpath
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 "core" modules are found in $ENUNCIATE_HOME/lib, where $ENUNCIATE_HOME is the path on the filesystem where the Enunciate distribution was unpacked. These "core" modules include the Enunciate engine itself, the documentation module, the Jersey module, the Enunciate REST module, the XML module, and the Spring app module.
Note the conspicuous abscense of any module dealing with the SOAP endpoints. This is because as of Enunciate 1.9, there are multiple modules available for processing the SOAP endpoints. You'll have to take your pick of XFire, CXF, or JAX-WS RI. You'll also note that the GWT and AMF modules are not included in the "core" Enunciate modules. Make sure you include on the Enunciate classpath any module libraries that are not included in the "core" module libraries. These are found in the $ENUNCIATE_HOME/lib/modules directory.
Enunciate Task Attributes
Here's a table of the additional attributes:
| attribute | description | required |
|---|---|---|
| dir | The base directory to scan for the source files to Enunciate. | No |
| configFile | The Enunciate configuration file to use. | No |
| target | The Enunciate target step. | No; defaults to "package". |
| generateDir | The directory to use as the output directory for the "generate" step. | No; defaults to a temp directory. |
| compileDir | The directory to use as the output directory for the "compile" step. | No; defaults to a temp directory. |
| buildDir | The directory to use as the output directory for the "build" step. | No; defaults to a temp directory. |
| packageDir | The directory to use as the output directory for the "package" step. | No; defaults to a temp directory. |
| scratchDir | A directory Enunciate can use as a scratch directory. | No; defaults to the system temporary directory. |
| gwtHome | The GWT home directory. | No |
| classpathRef | The reference to the classpath to use to Enunciate (used to find modules, invoke APT, and copy jars for building the war). | No; Defaults to the system classpath |
| compileDebugInfo | Whether to compile with debug info. | No; defaults to true. |
| verbose | Whether to print verbose output. | No |
| debug | Whether to print very verbose (debug-level) output. | No |
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 two additional nested elements.
- The classpath element is a path-like structure used to specify the Enunciate classpath for execution.
- The export element is used to specify an export. Here are its attributes:
| attribute | description | required |
|---|---|---|
| artifactId | The id of the artifact to export. | Yes |
| destination | The file or directory to which to export the artifact. | Yes |
Example
...
<path id="enunciate.classpath">
<fileset dir="${enunciate.home}/lib">
<include name="*.jar"/>
</fileset>
<fileset dir="${enunciate.home}/lib/modules/xfire">
<include name="*.jar"/>
</fileset>
<fileset dir="${java.home}">
<include name="lib/tools.jar"/>
</fileset>
</path>
<taskdef name="enunciate" classname="org.codehaus.enunciate.main.EnunciateTask">
<classpath refid="enunciate.classpath"/>
</taskdef>
<enunciate basedir="src/main/java">
<include name="**/*.java"/>
<classpath refid="enunciate.classpath"/>
<export artifactId="spring.war.file" destination="${tomcat.home}/webapps/myapp.war"/>
</enunciate>
...
Exports the fully-packaged, fully operational war (the artifact identified by the id "spring.war.file") to ${tomcat.home}/webapps/myapp.war, assuming ${enunciate.home} refers to the enunciate home directory. Note that it's important to include $JAVA_HOME/lib/tools.jar on the classpath when invoking Enunciate.
Command-Line Scripts
In the distribution bundle, you can find a bash script and a batch file that you should be able to use to invoke Enunciate. The script attempts to invoke org.codehaus.enunciate.main.Main with the full classpath. The scripts rely on the following environment variables being set:
| Variable | Description | Default Value |
|---|---|---|
| ENUNCIATE_HOME | The main directory where the Enunciate distribution is unpacked. | The parent directory of the directory containing the script. |
| ENUNCIATE_JAVA_HOME | The installation directory of the Java SDK that Enunciate is to use. | The value of the JAVA_HOME environment variable. |
| JAVA_HOME | The installation directory of a valid Java 5 SDK. | (none) |
The main argument(s) to the script are the list of source files that are to be enunciated. Options are passed passed with a dash ("-"). You will usually want to specify an artifact to export with the -E[artifactId] option. The following is a list of the other available options (options that specify a value will assume the argument after the option is the option value):
| option | value | Description |
|---|---|---|
| v | N/A | Print verbose output to the console. |
| vv | N/A | Print very verbose (debug) output to the console. |
| xg | N/A | Disable compiling with debug info. |
| f | configFile | Use [configFile] as the configuration file. |
| g | generateDir | Use [generateDir] as the output directory for the "generate" step. |
| c | compileDir | Use [compileDir] as the output directory for the "compile" step. |
| b | buildDir | Use [buildDir] as the output directory for the "build" step. |
| p | packageDir | Use [packageDir] as the output directory for the "package" step. |
| cp | classpath | Use [classpath] as the Enunciate classpath (used to find modules, invoke APT, and copy jars for building the war; defaults to the system classpath). |
| t | target | Use [target] as the target step, defaults to "package". |
| E[artifactId] | destination | Export the artifact identified by [artifactId] to the specified destination (file or directory). |
Programmatic Interface
The programmatic entry point is org.codehaus.enunciate.main.Enunciate. Just instantiate one of these, configure it as needed, and call execute(). Refer to the Javadocs and source code for more information.