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 (original and generated).
-
build
Used to assemble all the pieces of the API into a single logical structure.
-
package
Used to consolidate and package the assembled pieces.
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 loosly coupled, non-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 REST module validates the REST endpoints, the xfire-client module generates the xfire 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.
Enunciate ships with a default set of modules:
-
docs
Generates the API documentation.
-
jaxws
Generates the JAX-WS request/response/fault wrappers according to the JAX-WS specification
-
rest
Validates the REST API and provides support for hosting it.
-
xfire
Generates support classes for deploying SOAP endpoints (using XFire).
-
spring-app
Builds and packages the war that will host the documentation and service the endpoints (via Spring).
-
xfire-client
Builds the Java client libraries used to access the API (using XFire)
-
gwt
Builds the GWT client libraries used to access the API via GWT-RPC. It also compiles the configured GWT applications.
-
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.
-
xml
Generates the WSDL and schemas for the API.
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. Here are some of the more interesting configuration options:
-
label
The "label" attribute of the root element specifies a label for your Enunciate project.
-
api-import
If your API depends on classes outside your source base, these elements won't be included by default into the generated schemas and client code. The 'class' attribute of this element specified the FQN of an external class on which your API depends. By default Enunciate will scan the classpath for the source files that are associated with these additional classes. If the sources are not found, Enunciate will not be able to take advantage of source-specific information (e.g. documentation). You can disable scanning for source files by setting the 'seekSource' attribute to false.
-
deployment
The deployment element is used to specify the hostname and context on which your API will be deployed, so the WSDL and client code will know where the endpoints will be mounted.
-
namespaces
This section is used to define the prefixes for your namespaces.
-
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 more information, see the XFire module documentation and the REST module documentation.
-
modules
This is where the configuration of the modules goes. For specifics, see the documentation for each module.