Skip to content

Executables (Version 1)

Jump to bottom Edit New page
Ryan Heaton edited this page Sep 17, 2015 · 2 revisions

Invoking Enunciate (Version 1)

Enunciate can be invoked in a variety of different ways:

Keep in mind that there are a set of "core" Enunciate modules that you will likely always want enabled. There are also a set of "optional" modules that you may want to include depending on the features you want enabled. The default Enunciate invocation includes only the base set of modules, but adding optional modules is only a matter of adjusting the classpath.

See the Enunciate modules documentation for more information.

Maven

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

groupId artifactId modules included
org.codehaus.enunciate maven-enunciate-plugin all "base" modules
org.codehaus.enunciate maven-enunciate-spring-plugin all "base" modules + spring-app
org.codehaus.enunciate maven-enunciate-cxf-plugin all "base" modules except jaxws-ri and jersey + cxf
org.codehaus.enunciate maven-enunciate-jboss-plugin all "base" modules except jaxws-ri and jersey + jboss
org.codehaus.enunciate maven-enunciate-slim-plugin basic-app only

Note that some modules are not enabled in any plugin and will therefore have to be added to the plugin dependencies in order to include them. Most notable are the gwt and amf modules. Consider the following example demonstrating how to include the amf module:

<plugin>
  <groupId>org.codehaus.enunciate</groupId>
  <artifactId>maven-enunciate-plugin</artifactId>
  <version>1.29</version>

  <configuration>
    ...
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>assemble</goal>
      </goals>
    </execution>
  </executions>
  <dependencies>
    <dependency>
      <groupId>org.codehaus.enunciate</groupId>
      <artifactId>enunciate-amf</artifactId>
      <version>1.29</version>
    </dependency>
  </dependencies>
</plugin>

The maven-enunciate-slim-plugin can be used by those who want to have a tighter grip on which modules get included.

Runtime Classpath

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 plugin classpath defines the modules that are included at compile-time and depends on which plugin is being used (see above). The project dependency classpath defines the libraries that are to be used to compile and run the application.

Note that some modules (invoked at compile-time) will require certain runtime dependencies to be on the classpath (i.e. in WEB-INF/lib) when the application is run. For example, the spring-app module will require the spring dependencies in order for the application to run. To this end, Enunciate supplies a top-level runtime ("rt") dependency for each (compile-time) maven plugin that can be conveniently included in the project dependencies of an Enunciate project.

groupId artifactId use with plugin
org.codehaus.enunciate enunciate-rt maven-enunciate-plugin
org.codehaus.enunciate enunciate-spring-app-rt maven-enunciate-spring-plugin
org.codehaus.enunciate enunciate-cxf-rf maven-enunciate-cxf-plugin
org.codehaus.enunciate enunciate-jboss-rt maven-enunciate-jboss-plugin

Configuration

Note the following configuration parameters for each Maven plugin:

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.
additionalClasspathEntries String[] Additional entries (jars or directories on the filesystem) to add to the Enunciate classpath.
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.
addJavaClientSourcesToTestClasspath boolean Whether to add the generated Java 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.
javacArguments array List of additional arguments passed to Enunciate's Java compiler when compiling client-side code.
javacSourceVersion String javac -source version parameter
javacTargetVersion String javac -target version parameter

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 "java.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.ifyouwannabecool.war</groupId>
  <artifactId>ifyouwannabecool</artifactId>
  <packaging>war</packaging>
  <version>1.0</version>
  <name>ifyouwannabecool</name>
  <url>http://www.ifyouwannabecool.com</url>
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.enunciate</groupId>
        <artifactId>maven-enunciate-plugin</artifactId>
        <version>1.29</version>
        <configuration>
          <exports>
            <java.client.library.binaries>client.jar</java.client.library.binaries>
          </exports>
        </configuration>
        <executions>
          <execution>
            <goals>
              <goal>assemble</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  <dependencies>
    <dependency>
      <groupId>org.codehaus.enunciate</groupId>
      <artifactId>enunciate-rt</artifactId>
      <version>1.29</version>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.12</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 "base" modules are found in $ENUNCIATE_HOME/lib, where $ENUNCIATE_HOME is the path on the filesystem where the Enunciate distribution was unpacked. Optional modules (with their associated dependencies) 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
javacSourceVersion String javac -source version parameter
javacTargetVersion String javac -target version parameter
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 additional nested elements.

  • The classpath element is a path-like structure used to specify the Enunciate classpath 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 fully-packaged, fully operational war (the artifact identified by the id "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.

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

  <!--include (optional) spring module-->
  <fileset dir="${enunciate.home}/lib/modules/spring">
    <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="war.file" destination="${tomcat.home}/webapps/myapp.war"/>
  <javacArgument argument="-g"/>
</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 only the base modules classpath. The scripts rely on the following environment variables being set:

variable description default
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 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.

© 2023 Web Cohesion

Clone this wiki locally