User Guide (Version 1)

Note: The following is applicable to Enunciate 1.x. For the Enunciate 2 user guide, see User Guide.

The Enunciate engine can be invoked through a number of different ways, including via the command line, Ant, Maven, or programmatically. For more information on how to invoke Enunciate, see Executables.

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, then the engine 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).

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, faults, etc. This abstract form is called the API "model". Some errors in the API source are fatal. These will be thrown immediately and the engine will halt.

Validation

Once established, the model is then validated. There is a default "core" set of validation rules, and each module optionally carries with it a set of additional 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 IDL and schemas for the API, the Java 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.

For more information about modules, see Modules.

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:

attribute	description
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 ``` 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 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

The namespaces element is used to define the prefixes for your namespaces. For more information, see Custom Namespace Prefixes.

services

The services element 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

The webapp element is used to customize the way the application is compiled, built, and assembled into a web application archive (war). 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.

For more information about the webapp configuration, see Webapp Configuration.

modules

The modules element contains the configuration of each module. For more information, see Modules (Version 1).