The Basics

Enunciate is an engine for creating, maintaining, and deploying your Web service API for the Java platform, with a particular focus on support for Thin Server Architectures and SOFEA.

If that sounds complicated, it's not. All you have to do is define your service interfaces in Java source code. Make sure it's well-documented and that the metadata is correct, but don't worry about deployment descriptors, servlet configuration, packaging, or even interoperability.

Then invoke Enunciate.

Enunciate will build your web application and enforce its interoperability. And the app will include some impressive features, too:

• Full HTML documentation of your services.
• The endpoint(s) published via SOAP, REST, JSON, GWT-RPC, and AMF.
• Client-side libraries for rich client support.
• Interface Definition Documents (e.g. WSDL, XML-Schema, etc.)
• Etc.

An Example

So let's say you're developing a rich Flash client using Flex, and you've got to make some asynchronous Web service calls to your server. You've got your service interfaces defined in Java, and you need to make those interfaces available to your client. Sure, you could use JAX-WS to publish your services via SOAP. Or you could use RESTlet or Jersey to make them available via REST. Or perhaps you optimize for Flex and use BlazeDS to publish your services as AMF endpoints.

But for any of these choices, you've got to deal with the mess of deployment descriptors and keeping your documentation up-to-date. And let's face it, the Flex code you write isn't going to be pretty, since you'll be working with remote calls and loosly-typed objects.

This is a case where Enunciate is designed to make your life easier. Enunciate deals with your deployment difficulties, documentation, and client-side code. By using Enunciate to publish your service interfaces, not only will you have all three Web service interfaces (SOAP, REST, and AMF), but you'll also have full up-to-date documentation and generated, strongly typed ActionScript code that you can use to invoke your remote services from your Flex code. And it's all nicely packaged in a standard war that you can drop in your favorite application server.

There are many more cases where Enunciate can be applied. Whether you're developing a public API for application-to-application development, creating an AJAX application, or providing secure data to affiliate applications via OAuth, Enunciate will simplify both server-side and client-side development--without having to learn a any new development frameworks or libraries.

How

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 formal contract. This model is formalized as the "compiled contract" development model.

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. The documentation is in the form of both HTML docs and documentation for the generated client-side code.

• Multiple Endpoints: SOAP, REST, JSON, GWT-RPC, AMF, 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 XML REST endpoint at a different URL. Furthermore, certain REST endpoints will be automatically available as JSON endpoints at yet another URL. See the REST module documentation for more information.

  By enabling the GWT module, your endpoints will be published via GWT-RPC along with the client-side GWT code for invoking those endpoints via AJAX.

  By enabling the AMF module, your endpoints will be published via AMF and client-side ActionScript classes will be generated for Flex developers. Enunciate will even compile your Flex application, according to the configuration.

• Client Code Generation

  Enunciate will generate client-side code 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 WSDL but instead reflects it from the original source code, allowing code documentation to be carried over 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 other platforms (.NET, C++, PHP, etc.) in the future. Consult the roadmap for information on other modules in the pipe and how you can help.

• Clean, Consolidated Interface Definition Documents

  The common WS stack will provide a WSDL for an endpoint when queried. Generally, the WSDL is 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 a more complete discussion).

  Enunciate generates the formalized XML contract at compile-time, providing for a consolidated, efficient XML definition. Core schema data is consolidated into a single set of 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.

• Full App Packaging

  Enunciate packages your API, extended with each of the above features, into a single web application archive (war file), powered by Spring. 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.