Introduction
Welcome to the Enunciate user's guide! The assumption is that you've read through the getting started guide and are ready to understand a bit more of the details of how to use Enunciate.
The tone of this document will be much more quick and concise. It is presumed this document will serve more often as a reference and a jump point than as a full read.
Engine
The Enunciate engine is invoked through a number of different entry points, including via the command line, Ant, Maven, or programmatically. For more information on how to invoke Enunciate, see the executables page.
When the engine is invoked, the configuration is loaded and queried for the set of modules that will handle the work of enunciating the API. The modules are ordered and initialized. The engine then steps through its run phase. At the end of its run phase, each module is closed and the artifacts are exported as needed.
Run Phase Steps
The Enunciate run phase is separated into four distinct steps:
-
generate
Used to generate all source code and configuration files needed for handling the compilation, deployment, and packaging of the API. It is during this step that the API model is established and validated (see below).
-
compile
Used to compile the source code for the generated client-side libraries. Unless compilation is disabled, Enunciate will also use this step to compile your Web service API. If you're using Maven, compilation of your Web service API is not done by Enunciate.
-
build
Used to assemble all the pieces of the application (e.g. documentation, deployment descriptors, configuration files) into a single directory.
-
package
Used to package up the application (e.g. zip up the war file).
Each step carries with it certain core logic and then each module is given the chance to perform work for that step.
The Generate Step
The generate step is the most intensive and important step in the Enunciate process. It is during this step that the API model is established. This means that the source code for the API is read, analyzed, and loaded into an abstract form that represents the API in terms of the endpoint interfaces, data structures, REST endpoints, faults, etc. This abstract form is called the API model (or just "model" for short).
Some errors in the API source are fatal in that they prevent us from establishing the API model. These fatal errors will be thrown immediately and the engine will halt, unable to establish the model.
Validation
When the model is established, it is then validated. There is a default set of validation rules and each module optionally carries with it a set of validation rules. Validation rules include specification violations, interoperability constraints, and unsupported API definitions. Note, therefore, that it is at this step that interoperability and API clarity is enforced. Validation errors and warnings are accumulated and presented to the user before halting the engine. (In the case of only warnings, the engine will not be halted.)
Modules
The work of Enunciate is divided into modules. Modules can be thought of as loosely coupled, loosely-interdependant extensions to the Enunciate engine. Each module has a specific set of work to perform. For example, the XML module generates the WSDL and schemas for the API, the JAX-WS client module generates the Java client libraries, etc. Since each module has a specific set of work to do, each module has also a separate set of configuration options.
The modules that are to be included in the Enunciate mechanism are discovered at runtime using Sun's discovery mechanism.
There is a "base" set of modules that you will likely always want enabled. The "base" set is designed to enable the largest number of Enunciate features with a minimal dependency footprint. There are other "optional" modules that can be enabled according to the additional features that need to be applied. When invoking Enunciate, you will need to remember to add the necessary optional modules to the Enunciate classpath. For more information, see invoking Enunciate
Base Modules
-
basic-app
Assembles a basic J2EE web application (war) according to the Enunciate configuration.
-
c
Builds the C client libraries used to access the API.
-
csharp
Builds the C# client libraries used to access the API.
-
docs
Generates the API documentation.
-
java-client
Builds the Java client libraries used to access the API.
-
jaxws-ri
Generates support classes for deploying SOAP endpoints using JAX-WS RI.
-
jaxws-support
Generates the support files and classes necessary to support a JAX-WS application according to the JAX-WS specification.
-
jersey
Generates the support for deploying your endpoints according to the JAX-RS specification using Jersey.
-
obj-c
Builds the Objective C client libraries used to access the API.
-
php
Builds the PHP client libraries used to access the API.
-
xml
Generates the WSDL and schemas for the API.
Optional Modules
-
amf
Builds the AMF endpoints (and ActionScript client libraries for Flex developers) used to access the API via AMF. It also compiles the configured Flex applications.
-
CXF*
Support for using CXF as the SOAP and JAX-RS engine.
-
gwt
Builds the GWT client libraries used to access the API via GWT-RPC. It also compiles the configured GWT applications.
-
spring-app
Enables the API to run in the Spring container so as to be able to take advantage of things like dependency injection and AOP.
-
swagger
Builds the Swagger UI for the project.
*Since the default SOAP engine is JAX-WS RI and the default JAX-RS engine is Jersey, you will need to disable the jaxws-ri and jersey modules in order to use the CXF module. You will also need to enable the spring-app module since CXF depends on Spring. See these instructions for more information.
For more information about modules (including how to write your own), see the architecture guide.
Configuration
Configuration for the Enunciate engine (including any of its modules) is done in a single XML file that conforms to this schema. The configuration is defined by a top-level <enunciate> element. Here are some of the more interesting attributes applicable to this element:
-
label
The "label" attribute of the root element specifies a label for your Enunciate project. A label is useful because it is what often determines the names of some of the Enunciate-generated artifacts. For example, the names of your client-side libraries will be based on the project label. The default label is "enunciate". For Maven users, the default label is the project artifact id.
-
generatedCodeLicenseFile
The "generatedCodeLicenseFile" attribute of the root element specifies a file on the filesystem (relative to the configuration file) to be read as containing the text for the license governing any Enunciate-generated code.
The <enunciate> element also is configured with the following child elements. Note that not all configuration elements are listed here, but may be documented in other places like the FAQ.
disable-rule
The disable-rule element is used to disable some Enunciate rules, identified by an id. Note that not all rules can be disabled.
<enunciate ...>
...
<disable-rule id="..."/>
...
</enunciate ...>
facets
The facets element is used to configure how API facets are to be used in the project, such as to exclude certain API components from the generated documentation and client-side code. For more information, see API Facets.
<enunciate ...>
...
<facets>
<include name="Public"/>
<exclude name="Admin"/>
</facets>
...
</enunciate ...>
deployment
The deployment element is used to specify the hostname and context on which your API will be deployed. This may be necessary because Enunciate doesn't know at compile-time (although it tries to make reasonable guesses) where the application will be deployed at run-time.
<enunciate ...>
...
<deployment protocol="https" host="mydomain.com" context="/api"/>
...
</enunciate ...>
namespaces
This section is used to define the prefixes for your namespaces. For more information, see the FAQ entry.
services
This section is used to define custom configuration for specific services (SOAP and REST), such as the URLs at which to mount the endpoints. For example, by default, Enunciate puts the SOAP endpoints under the "/soap" context and the REST endpoints under the "/rest" context. The services element can be used to customize that.
<enunciate ...>
...
<services>
<soap defaultSoapSubcontext="/ws"/>
<rest defaultRestSubcontext="/api"/>
</services>
...
</enunciate ...>
webapp
This webapp configuration element is used to customize the way the application is compiled, built, and assembled. It provides hooks for customizing the web.xml file, for customizing the classes and resources that get included into the web application, and for adding additional files and resources to the application.
The webapp configuration element supports the following attributes:
- The "disabled" attribute can be used to disable the Enunciate application assembly. The default value is "false"
- The "dir" attribute specifies the directory into which to build the web application. The default value is a temporary directory.
- The "war" attribute specifies the war file that will be created. The default value is a temporary file.
- The "doCompile" attribute specifies whether Enunciate should take on the responsibility of compiling the server-side classes. This may not be desired if Enunciate is being used only for generating the war structure and configuration files. The default is "true" except for Maven users, for whom the default is "false".
- The "doLibCopy" attribute specifies Whether Enunciate should take on the responsibility of copying libraries to WEB-INF/lib. This may not be desired if the Enunciate is being used only for generating the war structure and configuration files. The default is "true" except for Maven users, for whom the default is "false".
- The "doPackage" attribute specifies whether Enunciate should take on the responsibility of packaging (zipping) up the war. This may not be desired if Enunicate is being used only for generating the war structure and configuration files. The default is "true" except for Maven users, for whom the default is "false".
- The "webXMLTransform" attribute specifies the XSLT tranform file that the web.xml file will pass through before being copied to the WEB-INF directory. No tranformation will be applied if none is specified.
- The "webXMLTransformURL" attribute specifies the URL to an XSLT tranform that the web.xml file will pass through before being copied to the WEB-INF directory. No tranformation will be applied if none is specified.
- The "mergeWebXML" attribute specifies the web.xml file that is to be merged into the Enunciate-generated web.xml file. No file will be merged if none is specified.
- The "mergeWebXMLURL" attribute specifies the URL to a web.xml file that is to be merged into the Enunciate-generated web.xml file. No file will be merged if none is specified.
- The "preBase" attribute specifies a directory (could be gzipped) that supplies a "base" for the war. The directory contents will be copied to the building war directory before it is provided with any Enunciate-specific files and directories.
- The "postBase" attribute specifies a directory (could be gzipped) that supplies a "base" for the war. The directory contents will be copied to the building war directory after it is provided with any Enunciate-specific files and directories.
- The "includeClasspathLibs" attribute specifies whether Enunciate will use the libraries from the classpath for applying the include/exclude filters. If "false" only the libs explicitly included by file (see below) will be filtered.
- The "excludeDefaultLibs" attribute specifies whether Enunciate should perform its default filtering of known compile-time-only jars.
Including or excluding jars from the war
By default, the war is constructed by copying jars that are on the Enunciate classpath to its "lib" directory (the contents of directories on the classpath will be copied to the "classes" directory). You add a specific file to this list with the "file" attribute of the "includeLibs" element of the "war" element.
Once the initial list of jars to be potentially copied is created, it is passed through an "include" filter that you may specify with nested "includeLibs" elements. For each of these elements, you can specify a set of files to include with the "pattern" attribute. This is an ant-style pattern matcher against the absolute path of the file (or directory). By default, all files are included.
Once the initial list is passed through the "include" filter, it will be passed through an "exclude" filter. There is a set of known jars that by default will not be copied to the "lib" directory. These include the jars that ship by default with the JDK and the jars that are known to be build-time-only jars for Enunciate. You can disable the default filter with the "excludeDefaultLibs" attribute of the "war" element. You can also specify additional jars that are to be excluded with an arbitrary number of "excludeLibs" child elements under the "war" element in the configuration file. The "excludeLibs" element supports either a "pattern" attribute or a "file" attribute. The "pattern" attribute is an ant-style pattern matcher against the absolute path of the file (or directory) on the classpath that should not be copied to the destination war. The "file" attribute refers to a specific file on the filesystem (relative paths are resolved relative to the configuration file). Furthermore, the "excludeLibs" element supports a "includeInManifest" attribute specifying whether the exclude should be listed in the "Class-Path" attribute of the manifest, even though they are excluded in the war. The is useful if, for example, you're assembling an "ear" with multiple war files. By default, excluded jars are not included in the manifest.
You can customize the manifest for the war by the "manifest" element of the "war" element. Underneath the "manifest" element can be an arbitrary number of "attribute" elements that can be used to specify the manifest attributes. Each "attribute" element supports a "name" attribute, a "value" attribute, and a "section" attribute. If no section is specified, the default section is assumed. If there is no "Class-Path" attribute in the main section, one will be provided listing the jars on the classpath.
The "globalServletFilter" element
The "globalServletFilter" element is used to specify a servlet filter that will be applied to all web service requests. It requires a "name" attribute and a "classname" attribute and supports an arbitrary number of "init-param" child elements, each supporting a "name" attribute and a "value" attribute.
The "resources" element
The "resources" element is used to specify a pattern of resources to copy to the compile directory. It supports the following attributes:
- The "dir" attribute specifies the base directory of the resources to copy.
- The "pattern" attribute specifies an Ant-style pattern used to find the resources to copy. For more information, see the documentation for the ant path matcher in the Spring JavaDocs.
The "resources" element
<enunciate ...>
...
<webapp disabled="[true|false] dir="..." war="..."
doCompile="..." doLibCopy="..." doPackage="..."
webXMLTransform="..." webXMLTransformURL="..."
mergeWebXML="..." mergeWebXMLURL="..."
preBase="..." postBase="..."
includeClasspathLibs="[true|false]" excludeDefaultLibs="[true|false]">
<globalServletFilter name="..." classname="...">
<init-param name="..." value="..."/>
</globalServletFilter>
<globalServletFilter name="..." classname="...">
<init-param name="..." value="..."/>
</globalServletFilter>
...
<resources dir="..." pattern="..."/>
<resources dir="..." pattern="..."/>
...
<includeLibs pattern="..." file="..."/>
<includeLibs pattern="..." file="..."/>
...
<excludeLibs pattern="..." file="..."/>
<excludeLibs pattern="..." file="..."/>
...
<resource-env-ref name="..." type="..."/>
<resource-env-ref name="..." type="..."/>
...
<resource-ref name="..." type="..." auth="..."/>
<resource-ref name="..." type="..." auth="..."/>
...
<env name="..." type="..." value="..."/>
<env name="..." type="..." value="..."/>
...
<manifest>
<attribute name="..." value="..."/>
<attribute section="..." name="..." value="..."/>
...
</manifest>
</webapp>
...
</enunciate ...>
For more information, see the documentation for the basic app module.
modules
This is where the configuration of the modules goes. For specifics, see the documentation for each module.