Introduction

Enunciate is a web service deployment framework. It is not another web service stack implementation. Rather, enunciate leverages existing web service technologies to provide a mechanism to build, package, deploy, and to clearly, accurately deliver your web service API on the Java platform.

Enunciate's novel approach to web service development centers around leveraging all components of an API that are definied and maintained in original source code, as opposed to only those that are defined by compiled bytecode. This means that web service development is done completely in source code, where it can be maintained using your favorite IDE and where the development entry barrier is low.

However, by starting with original source code, Enunciate avoids the interoperabilty issues of code-first development by forcing developers at compile time to reconcile any ambiguities or other potential hazards in the resulting authoritative XML contract. This philosophy is formalized as the "compiled contract" philosophy.

Of course, ease of development is not the only benefit of Enunciate's unique new approach to web service development:

Features

Starting from original source code allows Enunciate to provide an attractive set of capabilities and features far beyond your average WS stack. These include the following:

• Full User Documentation

  Enunciate will generate full user-level documentation to describe your web API. The content for the documentation is taken from the documentation of the original source code (i.e. javadoc), consolidating the maintenance of your entire web service contract to a single place.

• Consolidated, Annotated WSDL and Schemas

  The common WS stack will provide a WSDL for an endpoint when queried. The WSDL is almost always generated at runtime, the associated schema is inline, the semantic constructs (i.e. namespaces, message names, argument ids, etc.) are awkward and inconsistent, and the scope is limited to that specific endpoint. The XML contract is difficult to interpret (especially when being consumed for client-side stubs) and doesn't give a consolidated picture of the whole API because it has no reference to other endpoints and schema data that service the same namespace (click here for an example).

  Enunciate generates the formalized XML contract at compile-time, providing for a consolidated, efficient XML definition. Core schema data is consolidated into single schema documents (grouped by namespace), and multiple endpoints that service the same namespace are put into a single WSDL. This allows for a wider, cleaner picture of the formal contract and relieves the consumer of the consolidation work.

• Client Code Generation

  Enunciate will generate client code for multiple platforms to interface remotely with your published API. Not only is the generated code fully documented, but it is simple, elegant and efficient. Enunciate does not generate client code from the formal XML contract (i.e. WSDL) but instead reflects it from the original source code, allowing code documentation to be extracted from the existing code documentation (i.e. javadoc) and preserving valuable information like method signatures, class structure, and variable names.

  Currently, Enunciate generates code for the Java 1.4 platform and the Java 5 platform, but has plans to add modules that generate code for the .NET and C/C++ platforms in the near future. Consult the roadmap for information on other modules in the pipe and how you can help.

• Multiple Endpoints: SOAP, REST, etc.

  Enunciate will publish your endpoint class as a SOAP endpoint as defined by the JAX-WS annotations (powered by XFire). By supplying additional metadata, the same endpoint class will be published as a REST endpoint at a different URL. Future support for a JSON endpoint is pending. See the user guide for more information.

• Full App Packaging

  Enunciate packages your API, extended with each of the above features, into a single web application archive (war file). Drop the war file into your favorite J2EE container, and consider your web API enunciated.

Design and Philosophy

Enunciate boasts a clean, well-tested, modular design with loosely-coupled and easily extensible components, with a strong focus on testability. The Enunciate engine is highly configurable but supplies a reasonable default configuration so as not to require complexity. Enunciate aims to maintain a low entry barrier by adhering to published and proven standards and technologies so developers don't have to learn a new technology to be effective.

Enunciate's primary goal is to enable the web service developer without being obtrusive.

About

Enunciate is an open-source project, licenced under the Apache License, version 2.0. It was designed and built by Ryan Heaton, working for familysearch.org. Comments, enhancements or bug fixes to the project are welcome.