1 2 Previous Next


17 posts

Over at FamilySearch, I've been involved in supporting Flash application development that consumes a public POX API. It's not a REST API, but like REST, we provide a set of resources that are accessible at a given URI. Up to this point, our Flash developers have been stuck with parsing the resources as XML. It works fine, but it's not without a significant overhead.  XML isn't the most efficient data format, nor is it very convenient to work with in ActionScript code.

The "native" data format for flash development is AMF.  When ActionScript objects get written to a stream, they are serialized as AMF.  When the objects are read from a stream, AMF is the presumed deserialization format. The Enunciate project has provided support for supplying SOAP endpoints as AMF services for quite some time now, but I've only recently added support for AMF REST endpoints.

Here's the wrap-up of the process. As mentioned in the article, if you're already using Enunciate, this process will be significantly simpler. Enunciate already comes with a JAX-RS provider that does the serialization and it will generate your client-side ActionScript classes for you. Not to mention the fact that Enunciate will also generate documentation for your API and neatly package it up, ready to be deployed into your favorite servlet container.


So you've got your JAX-WS or JAX-RS endpoints defined and implemented, and they're compiling, building and running smooth on your server. All is well, right? You've been diligent in documenting and testing your code, and the consumers of your API seem to be happy.

Well, that's just because they don't know what they're missing.

Here's the thing: your Web service API could be so much better. What if you could leverage all that work you've put into your JavaDocs and publish that as documentation for your API?  And what if you could provide fully-documented, well-formated, strongly-typed client-side code for your .NET, Java, or ActionScript clients?

With just some enhancements to your build file or your POM, you can produce stuff that looks like this for your Web service API.

Let's say you're using Maven to build your project.  Just use the Maven Enunciate Plugin to export your own docs to the target/docs directory:


Or if you're using Ant, you can do the same thing with something like this:

<enunciate basedir="src/main/java">
  <include name="**/*.java"/>
  <classpath refid="enunciate.classpath"/>
  <export artifactId="docs" destination="target/docs"/>

That's it. Try it out. Check out the Enunciate documentation to learn more.


As of version 1.10, Enunciate will generate elegant client-side C# code and supply an AMF provider for your REST endpoints.

There is also a new Maven plugin that can be used to generate just the user documentation and client-side classes for your JAX-WS and JAX-RS endpoints.  If you're using JAX-WS or JAX-RS, you ought to try it out and witness the value-add for yourself.



Enunciate 1.9 Released Blog

Posted by stoicflame Jan 22, 2009

Enunciate 1.9 provides support for JAX-WS RI and CXF and generates a lightweight JAX-WS client-side library for accessing the endpoints.


For more information on how to use CXF with Enunciate:


Enunciate 1.8 was recently released with support for JAX-RS annotations. This means that Enunciate will now be able to process your Web service API as defined by JAX-WS (for SOAP endpoints) and JAX-RS (for REST endpoints).  If you already have your endpoints defined via JAX-WS and/or JAX-RS, it might be a good time to check out the additional features that Enunciate can provide.

  • Full User Documentation
    Enunciate will generate nice HTML documentation for your Web service API, scraped from the JavaDocs.
  • Client-Side Code
    The documentation will have links to download client-side code that Enunciate generated to be able to invoke your service operations via the Web service API.
  • WSDLs, Schemas, etc.
    The WSDLs and Schemas were generated by Enunciate from the source code, so they're consolidated, well-formatted, and documented.
  • Additional Endpoints
    Enunciate will publish your JAX-WS endpoints as GWT RPC endpoints and AMF endpoints (for Flex clients)

Enunciate 1.8 also added support for GWT 1.5 and a hefty set of bug fixes and minor enhancements


OAuth is Handy Blog

Posted by stoicflame May 15, 2008

Enunciate 1.7 has been released!

The primary feature of Enunciate 1.7 is support for securing your Web service endpoints using Spring Security.  There is additional support for OAuth, with OpenID and WS-Security planned for 1.8.

In addition, Enunciate 1.7 introduces the concept of custom REST content types, which you can use to support custom serialization formats for REST responses (beyond the default XML and JSON endpoints).



If you haven't checked out the Enunciate project recently, you may want to give it another look to see how it can improve the development, deployment, and consumption of your Web service API.

Enunciate 1.6 was just released with support for mounting your JAX-WS endpoint classes via AMF (thanks to Adobe's release of BlazeDS). This should be really interesting to Flex developers.  Not only will you be able to make Web service calls via AMF, but Enunciate will also generate type-safe client-side ActionScript classes that will access those endpoints.

Enunciate will also publish your endpoints via SOAP, REST/XML, JSON, and GWT. You'll also get your WSDLs, schemas, and full user-level documentation of your Web service API.

I'll be shortly posting a two-part tutorial on how to publish this kind of a rich API with your service endpoints and how to write an AJAX app with an embedded Flash component that consumes it.


Enunciate 1.5 Released Blog

Posted by stoicflame Oct 21, 2007

Enunciate 1.5 makes some dramatic improvements in the GWT application development experience.  Included in the distribution bundle is a new pet clinic sample application that will demonstrate how to publish the pet clinic Web service API and how to develop a nice AJAX app for the pet clinic using GWT.


The honeymoon with RESTful Web services is over. Now that we've had some time to get over the infatuation, let's take a fresh look at the principles of sound Web service API design.  Despite how rocky our relationship with SOAP has been, it's time to confront our prejudices and accept both technologies for their virtues and vices.

In fact, I propose we give this discussion a new identity in order to help us put the painful memories, bitter tears, and long, sleepless nights behind us. Because it's not really about REST vs. SOAP anymore, is it? A well-designed Web service API is so much more important than the technology we use to implement it. So after we get past the name-calling and mud slinging, what we're left with is a set of fundamental architectural principles for Web service API design.

On the REST side of the playing field we have engineers who have a set of well-defined resources that they want to make available by defining a constrained set of basic operations that can be applied. On the other side, we have engineers whose operations are much more complex, maybe contextual, and perhaps interdependent.  These engineers may or may not have a well-defined set of resources to which these operations apply. Rather than making a set of resources available, these engineers have a set of services they want to make available.

So on one end of the spectrum we have the need to design a Resource-Oriented Interface (ROI).  On the other end, we have the need to design a Service-Oriented Interface (SOI).

Determining what kind of an API is to be published should be the first step in designing a good Web service API. And, trust me, it's not always easy to determine where your API fits.  You may, for example, have a well-defined set of Gismo objects to which you can limit your operations to be create, read, update, and delete.  But what if you want to provide a search operation for Gismos?  In this case, the boundaries of the resource and the operation are less clear.

In any case, you will be able to make a much better choice of a development technology if you can first define whether your API is more Resource-Oriented or Service-Oriented. (By the way, it'll probably fit somewhere in between.) Choosing the development technology first is letting the tail wag the dog.

Still unconvinced?  May I suggest that you subscribe to one or more of the common misconceptions about the current state of Web service development?  Let's debunk those right now, shall we?

  1. It is not easier to design a good Resource-Oriented Interface (think "REST") than it is to design a good Service-Oriented Interface.  Actually, I'd suggest that for most engineers, an SOI is more intuitive than a ROI.
  3. It is not easier to implement an ROI than it is to implement an SOI. In fact, the tools these days are much more mature for SOI. I've found that ROI developers often have to work directly with low-level protocol APIs, although that's changing fast.
  5. It is not easier to consume an ROI than it is to consume an SOI. Which type of interface is easier to consume always depends on the platform of the consumers.  Are they using a high-level, compiled programming language or are they in looser, more interpreted environment?
  7. An SOI is not any less interoperable than an ROI. I'm going to assert that we've pretty much solved the issue of interoperability. I'm sure there are many of you who might disagree.  Bring it on.
  9. SOAP is not the only technology for implementing an SOI. Really. Just because you have a more service-oriented API doesn't mean you have to use SOAP. (Really? Whew!)
  11. ROI is not always the best choice for supporting RIAs. Many AJAX frameworks (e.g. GWT) have their own RPC mechanisms that are much more SOI than they are ROI. Another example for Flash is AMF.

So what do you think?  I say let's adopt a rational, reasonable approach to Web service API design and stop letting the tail wag the dog.

When you use Enunciate 1.4 to publish your Web service API, Enunciate will build you a war that you can drop into your favorite webapp container.  The war will supply any or all of the following, depending on your configuration:

  • Full documentation (scraped from the JavaDocs)
  • Your service beans mounted via SOAP, along with the formal contract (WSDL, schemas, etc.)
  • Those same service beans mounted via REST/XML.
  • Those same service beans mounted via JSON.
  • Those same service beans mounted as GWT-RPC endpoints.
  • Client-side libraries for download (used for invoking your API programatically via SOAP).
  • Client-side GWT Java libraries that can be used with GWT to support an AJAX app.
  • Etc.

If you want to know more, I suggest a quick walk through the getting started guide.



Enunciate 1.3 Released Blog

Posted by stoicflame Aug 22, 2007
Enunciate 1.3 includes support for applying aspects to service beans, customization of endpoint URLs, and many bug fixes and minor enhancements. See the release notes for details.

Enunciate 1.2 Released Blog

Posted by stoicflame May 30, 2007
Maps and support for type adapters were the two features most requested from those using Enunciate (and the two features that most often precluded more use from those wanting to use Enunciate). Of course, the release includes numerous bug fixes and some user experience enhancements. http://enunciate.codehaus.org

Filter Blog

By date: