Enunciate: Java code-first, compiled-contract WS deployment framework

Posted by James Kao on Apr 03, 2007

Sections

Enterprise Architecture,

Operations & Infrastructure,

Process & Practices,

Development

Topics

SOAP ,

WSDL ,

Java EE ,

Messaging ,

Java ,

SOA Platforms ,

Web Services ,

SOA ,

Languages ,

Build systems ,

SOA Appliance ,

Enterprise Architecture ,

Programming ,

Architecture ,

XFire ,

Apache Axis

enunciate 1.0, a J2EE web service deployment framework that provides a complete development-to-deployment system for creating SOAP, REST, and JSON endpoints, was released last week.  enunciate has been generating interest on blogs and forums. enunciate is not a web service stack like Axis2 or XFire. Rather, it uses XFire and Spring to provide a code-first development model (not in itself novel) that enforces compatibility contracts at compile time:

Enunciate's novel approach to Web service development centers around leveraging all components of an API that are defined 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.

Robert Cooper writes that enunciate: "will take a Java service implementation as a set of POJOs, or JSR-181 annotated stuff, and spit out a WAR file with an Xfire backed SOAP service, a REST service, a JSON service and some fairly nice looking Docs scraped off the JavaDoc."

The key is the addition of a "generate" step that occurs prior to the compile-build-package activities for a project. This step not only generates boilerplate code to surround a developer's service classes, but also validates the API model:

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. 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.)

While enunciate describes code-first and the "compiled contract" development model as a feature, others pointed out that code-first has proven not to work - the only way to ensure that you can have ensure both interoperable web services and long-lived services (those that allow you to change your underlying code without breaking the public API) is to adopt a contract-first approach.  Ryan Heaton from enunciate pointed out that in response once should be careful to use versioning when appropriate and that "interoperability rules are enforced" but at compile time, but that enunciate did not have clear support for contract-first development at this time.

The future roadmap for the project includes support for features like end-point versioning, .NET clients, SMTP endpoints, WS-*, and even generating a standalone web service server instead of just a WAR.