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".
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. 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. |
| 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 |
| 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}">
<include name="enunciate-full-*.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.
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.
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. |
| outputDir | File | The destintation directory for exports. Defaults to the project build directory. |
| 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 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. |
| 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.7</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.7</version>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>3.8.1</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
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 (see dependencies). 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. |
| 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.