Web Cohesion is pleased to announce the release of Enunciate 1.0. Enunciate is an open-source Web service deployment framework. The idea is simple: you develop your complete Web service API in source code. Make sure it's well-documented and that the metadata is correct, but don't worry about deployment descriptors, servlet configuration, or packaging, or even interoperability. From your source code, Enunciate will build a fully-documented, interoperable web application in the form of a web application archive (war file). A consolidated, annotated XML contract is generated at compile-time. Each service class is published as a SOAP endpoint, a REST endpoint, and a JSON endpoint according to the supplied metadata. Enunciate leverages JAX-WS and JAXB annotations, but is not a full implementation of either of those specifications. Enunciate enables code-first development, but enforces interoperability at compile-time (the "compiled contract" development model). Client-side libraries for multiple platforms are also generated and made available for download from the web application. Be sure to walk through the getting started guide, where you'll see an example of the straightforward, enabling approach to Web service development that Enunciate facilitates. And the getting started guide is more than just a "Hello, World" example; it's got multiple services, complex objects, web faults, and binary attachments. 1.0 is only the first public release version of Enunciate; there are a lot more features planned on the roadmap.

Sounds like a nice utility, but I have a question about statement... "a REST endpoint, and a JSON endpoint" What is a JSON endpoint? I hope the author doesn't see a difference between REST and JSON, or thinks that REST uses xml encoding to communicate. You can use SOAP envolopes with REST for all you care, so there should really be two endpoints, SOAP and REST and REST should allow the application to somehow declare it's communication protocol. This is where WADL shines. Ilya

I hope the author doesn't see a difference between REST and JSON

Oooo... you're absolutely right. This one's my bad. What I mean by REST in this context is XML. So what it should *really* read is "a REST XML endpoint and a REST JSON endpoint."

so there should really be two endpoints, SOAP and REST and REST should allow the application to somehow declare it's communication protocol.

Yes, the REST/JSON endpoint is published at a different URL from the REST/XML endpoint, which is published at a different URL from the SOAP endpoint. And as for WADL, it's already on the roadmap.

Sounds like a great idea and addresses exactly one of the problems we're thinking about at the moment: whether we should standardize our growing number of web services to use SOAP or REST in order to keep things simple. Looks like Enunciate could really help us to have both without much development overhead. The documentation feature looks also very promising. I'm looking forward to play around with it to see how good it really is. Daniel

I was really excited when I first saw this project, and walked through the excellent getting started guide. However, I soon realized this tool not only processes the source code, but compiles and builds the war. Unfortunately, this makes it unusable in a Maven 2 environment where Maven is responsible for building and packaging the war, among other things. Would it be possible to split out the source generation from the artifact generation? I'd love to be able to let Maven 2 compile my code, let Enunciate generate the service interfaces and documentation, then have Maven 2 package the war. BTW, excellent job on the documentation! You just don't often see Open Source project documentation of that quality and detail.

I'd love to be able to let Maven 2 compile my code, let Enunciate generate the service interfaces and documentation, then have Maven 2 package the war.

I totally agree! Maybe you could wrap up all these actions into an own Maven2 goal which does all the magic at once. I bet this would be very useful for a lot of developers out there.

Maybe you could wrap up all these actions into an own Maven2 goal which does all the magic at once. I bet this would be very useful for a lot of developers out there.

Sounds good. I'll add a task in JIRA. Anybody want to help?

Would it be possible to split out the source generation from the artifact generation? I'd love to be able to let Maven 2 compile my code, let Enunciate generate the service interfaces and documentation, then have Maven 2 package the war.

Oh, support for this is already there. I guess my documentation wasn't clear enough about this... I'll see what I can do to clarify. Anyway, you'll see that there are four steps to the engine: generate, compile, build, and package. At each step, certain artifacts are created made available for export. Most of the artifacts are created at the "generate" step. These include the documentation, the WSDLs and schemas, the client-side source code, etc. The "compile" step is for compiling the classes, the "build" step is for assembling everything in a logical file structure. Then, the war isn't created until the "package" step. Anyway, you can export any of the artifacts that are created at any step in the process. You'll want to refer to the documentation of the module that creates the artifact to find out what artifacts are available for export. For example, to find out about the documentation artifact, check out the docs for the docs module. And if you don't want Enunciate to compile anything, just tell it to target the "generate" step. (The default step is "package.") Having said all that, assembling the war is kind of complex... are you sure you trust Maven to do that? (You can tell I'm not a Maven guy.) Why do you *want* Maven to build the war if it's already built? And, by the way, one of the artifacts exported at the "build" step is the open directory that will be zipped up as a war during the package step. You could export just that, do what you want to it, and have Maven take it from there. The mailing lists are open, as is the WIKI. Help me provide better documentation and support for Maven users! What do I need to clarify?

BTW, excellent job on the documentation! You just don't often see Open Source project documentation of that quality and detail.

Thanks! I just wanted to tie-up all the loose ends.

http://www.jyog.com

When you make a public API, you should define your contract at design time, not runtime (the ugliest of uglies), and not compile time. When you want to create a public Java API, do you generate your UML schemas from your code ? I hope not. I hope you think out your API before coding it. Do the same for web services ; don't throw away good practices because your output is SOAP or XML REST or JSON REST.

And.... QUE THE ZEALOTS! I'll intentionally not go down the road of the Agile vs. Waterfall and BDUF vs. TDD etc. debate. However, I will state that in fact yes, I know MANY people who generate UML from code just to have as a more easily digestible reference. Some people think that since code is the language that most developers are most fluent in, it's also the best suited to fleshing out detailed designs (no argument on high level design... at least SOME has to be done or you're begging for a disaster) (back on topic) Seriously though, aside from the cool new toys, how is this significantly different than code first? I see all the cool bells and whistles, such as user documentation, SOAP / REST, etc., but the claim of increased inter operability confuses me. Is the assumption here that all code first tooling produces non inter operable contracts? Or that the compiled contract tooling will always produce contracts in the same manner... even across implementations? If you change the code using enunciate (refactoring, etc.), you're still likely to break that contract as the contract will have to be regenerated. Whether it's regenerated at compile time, or runtime, who cares? How is this significantly different than what's already available with other code first type tool sets. Help me understand this.

how is this significantly different than code first? ...Is the assumption here that all code first tooling produces non inter operable contracts?

The biggest difference is the stipulation that interoperability rules are enforced, and that they're enforced at compile-time. I was careful not to say that all code-first tooling produces non inter operable contracts. Actually, I think the resources for code-first development are getting much more viable these days.

If you change the code using enunciate (refactoring, etc.), you're still likely to break that contract as the contract will have to be regenerated.

Oh, sure. You still have to be careful to version.

Whether it's regenerated at compile time, or runtime, who cares? How is this significantly different than what's already available with other code first type tool sets.

I don't know of a single runtime contract generator that actually attempts to enforce interoperability rules, so you never actually uncover interoperability issues until someone is trying to consume the API. But even if interoperability rules were enforced, wouldn't you rather be informed about issues at compile-time? That's one reason I prefer Java over some runtime-interpreted scripting language; I don't like having to attempt to run my program to find out about compile errors. Of course, I recognize there are plenty of people who choose runtime-interpreted languages over Java.

When you make a public API, you should define your contract at design time, not runtime (the ugliest of uglies), and not compile time.

"The ugliest of uglies," huh? Personally, I think defining your API in WSDL/Schema is much more ugly than defining it in Java. WSDL's nasty. I don't think I'm the only one who would rather define my interfaces and API in an environment with which I'm proficient. That is, as long as I have some assurance of interoperability.

Well, if you don't like WSDL, then don't use it and don't use SOAP. It's great if you can get your public contract up and running very quickly by using your Java code, but I can assure you that when actual users are going to use your web service, you're going to waste a lot of time trying to make it work, and you're going to dive into the wsdl (and dive into frameworks incompatibilities) anyhow. I have examples when Axis2 1.2 can't event read XML it has written itself ! You can imagine what happens with other toolkits' XML... It's sad, but true, that web services toolkits are slightly incompatible with one another. We've got to live with it for now, until things get better. I think that contract first is a good practice in any cases, but right now, it's the only one that's really working. Well, unless you know you will never use a client toolkit different from your server toolkit. In which case I don't know why you're using web services in the first place...

I can assure you that when actual users are going to use your web service, you're going to waste a lot of time trying to make it work, and you're going to dive into the wsdl (and dive into frameworks incompatibilities) anyhow.

I understand your scepticism: it's never worked before. But this time it will. There will be a time in the near future where Enunciate will generate the client-side code for more platforms: .NET, Ruby, Python, C/C++, whatever. And it will include tests that prove the generated client-side code works. And it can generate clear, unambiguous client-side code because it will not be generated from WSDL, but directly from the Java source code.

We've got to live with it for now, until things get better.

I refuse to "live with it." I'm going to help "things get better" starting now.

I refuse to "live with it." I'm going to help "things get better" starting now.

There are different scenarios for web services, and for at least one kind, I don't think there's any choice but to "live with it". If you are defining an interface for an external client, and you want the flexibility to change your code as you see fit while maintaining that interface, I don't see any alternative to contract-first. In this scenario, getting compile-time warnings provides no benefit, because my goal is to be able to change the code however I see fit. Either I can change my code or I can't. With contract-first, I know I can change it and still adhere to the interface (even if I have to build an adapter layer on top of it). So it may be that "things get better" for a particular scenario of using web services, but this won't improve what I would assume is a fairly common scenario for web services.

If you are defining an interface for an external client, and you want the flexibility to change your code as you see fit while maintaining that interface, I don't see any alternative to contract-first.

Sure. Speaking generally, if you have to maintain an existing contract that you don't control, contract-first is your only option. I need to give some thought on how to support this kind of scenario at compile-time. Any ideas?

Well, if you don't like WSDL, then don't use it and don't use SOAP.

It's great if you can get your public contract up and running very quickly by using your Java code, but I can assure you that when actual users are going to use your web service, you're going to waste a lot of time trying to make it work, and you're going to dive into the wsdl (and dive into frameworks incompatibilities) anyhow. I have examples when Axis2 1.2 can't event read XML it has written itself ! You can imagine what happens with other toolkits' XML...

It's sad, but true, that web services toolkits are slightly incompatible with one another. We've got to live with it for now, until things get better. I think that contract first is a good practice in any cases, but right now, it's the only one that's really working. Well, unless you know you will never use a client toolkit different from your server toolkit. In which case I don't know why you're using web services in the first place...

I don't know why use web services in any place.... I don't think that is (only) a matter of contract first or last. There are two different aspect: 1. Interoperability 2. Versioning I think that besides tools slight (!) incompatibility, the problem maybe reside in the spec that allows incompatibility. About versioning the only thing that I can say that is a real and the only reasonable way to handle it seems to be the facets of ICE (www.zeroc.com). Guido

About versioning the only thing that I can say that is a real and the only reasonable way to handle it seems to be the facets of ICE

I've got good Enunciate support for versioning on the roadmap, too.

About versioning the only thing that I can say that is a real and the only reasonable way to handle it seems to be the facets of ICE

I've got good Enunciate support for versioning on the roadmap, too.

It is a runtime problem. Contract design time/deploy time management is only the "simple" side of the problem. Guido

i thought crispy ( http://crispy.sourceforge.net/ ) was doing something similar..

i thought crispy ( http://crispy.sourceforge.net/ ) was doing something similar..

Crispy is more on the client side, to use similar code to call SOAP, XML-RPC, ... I think that it's more similar to XINS ( http://xins.sourceforge.net/ ) (2.0 will add JSON).

I think that it's more similar to XINS.

Yep, much more like XINS. Only XINS supports a contract-first development model. I don't want to choose contract-first development unless I have to.

I've recently used xfire to expose some java functionality into a JSR 181 compliant web service. I liked it because it was easy to integrate using maven and spring (see http://www.memestorm.com/blog/basic-spring-web-services-with-xfire-and-jsr-181/) How would you compare Enunciate to XFire in terms of ease of integration? Could it be wired up using Spring? Cheers, defo like the generated html web service docs, nice work! Chico

Enunciate uses XFire on top of Spring to deploy its web services. Basically, you use Enunciate to build and compile your JSR 181-annotated source and it produces a fully-configured war file for you that you can drop into your favorite J2EE application container. The war file will not only publish your classes as SOAP endpoints, it'll publish them as REST/XML endpoints and REST/JSON endpoints, depending on how you've annotated them. The deployed web application also publishes full user-level documentation and makes client-side libraries available for download from a download page. With Enunciate, you don't have to worry about any Spring configuration or any XFire configuration unless you want to (in which case there are hooks available for you). I like XFire/Spring, too. That's why I chose it for Enunciate. But despite how nice it is, Enunciate takes the web service development process to a whole new level. Try it. You'll be impressed.

Sounds Intersting Want to know more ........