Enunciate Your Web Service API

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.

Re: Enunciate Your Web Service API

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

Re: Enunciate Your Web Service API

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

Re: Enunciate Your Web Service API

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



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.

Maven support?

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.

Re: Maven support?

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.

Re: Maven support?

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?



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

Re: Maven support?

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

Re: Enunciate Your Web Service API

http://www.jyog.com

Contract first development, dammit !

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.

Re: Contract first development, dammit !

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.

crispy?

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

Re: Contract first development, dammit !

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

Re: crispy?

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

Re: Contract first development, dammit !

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.



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



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.

Re: crispy?

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.

Re: Contract first development, dammit !

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

Re: Contract first development, dammit !

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.


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

Re: Enunciate Your Web Service API

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

Re: Enunciate Your Web Service API

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.

Re: Contract first development, dammit !

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.

Re: Contract first development, dammit !

<mode-serious-on>
I don't know why use web services in any place....
</mode-serious-on>

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

Re: Contract first development, dammit !

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?

Re: Contract first development, dammit !

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

Re: Contract first development, dammit !

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

Guido

Good

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

New Features in EJB 3.1 - Part 5

In this last article of the series, Reza Rahman will talk about standardized global JNDI names for Session Beans and EJB 3.1 Embeddable Containers for Java SE environments. (October 8, Article)

---

A RESTful Core for Web-like Application Flexibility - Part 4 - Patterns

Randy Kahle and Tom Hicks conclude their four-part series on resource-oriented computing by describing how to utilize a RESTful kernel to design and build software systems. (October 6, Article)

---

UseMon Real-Time JVM Monitoring

Paul Rene Jørgensen talks about UseMon, an efficient, open-source, real-time JVM performance monitoring agent. (October 2, Tech Brief)

---

Extreme Transaction Processing, Low Latency and Performance

In this podcast, John Davies will cover several case studies of extreme transaction processing, low latency and high performance systems and offer insight into what we might expect to see in mainstream in the near future. (September 29, Podcast)

---

OpenESBs in Action

Learn about Mule, ServiceMix, Synapse, Petal and other OpenESBs in Action from authors Tijs Rademakers and Jos Dirksen - Tech Brief about their new book. (September 24, Tech Brief)

---

Getting Started with jBPM and Spring

Josh Long looks at business process management using jBPM and Spring to implement a simple multi-stage operation. (September 22, Article)

---

Java Performance Tooling

In this podcast, Holly Cummins will introduce a number of tools for identifying and fixing common Java performance problems. (September 17, Podcast)

---

Terracotta Brings Large Memory Spaces to Java

In this podcast, TheServerSide.com editor Peter Varhol asks Terracotta CTO Ari Zilka about how the software works and what it can be used for. (September 15, Podcast)

---

Object Oriented JavaScript Demonstrated

In this chapter from his book Object-Oriented JavaScript, author Stoyan Stefanov talks about primitive data types in JavaScript as a prelude to discussing more complex concepts. (September 12, Chapter)

---

The JSF Flex Project

The JavaServer Faces Flex project lets developers unfamiliar with Flex create JavaServer Faces components to link Flex UIs to managed beans in the same manner as JSF. (September 8, Article)

---

What is an App Server?

Joseph Ottinger notes that we have certain preconceived notions as to what an app server is and does, and argues that we should rid ourselves of those notions. (September 2, Article)

---

A RESTful Core for Web-like Application Flexibility - Part 3 - Logical Level Programming

Randy Kahle and Tom Hicks continue their series on Resource Oriented Computing with a description of the transition between the physical and logical level of their architecture. (September 2, Article)

---

Building a Scalable Enterprise Applications Using Asynchronous IO and SEDA Model

Mihai Lucian demonstrates a Java servlet architecture using Mule that supports asynchronous I/O and a combination of fast and long-running business processes. (August 25, Article)

---

Asynchronous Processes Modeled as Persistent Finite State Machines

Benjamin Possolo describes and implements a finite state machine for asynchronous services using JEE. (August 18, Article)

---

A RESTful Core for Web-like Application Flexibility - Part 2 - Microkernel

Randy Kahle and Tom Hicks continue their series of RESTful computing with an explanation of the role of the microkernel. (August 7, Article)

---

Putting Physhun To Work

Read more about the Physhun finite state modeling framework in Jim Ladd's article on a real life application. (August 5, Article)

---

Are Java Web Applications Secure?

HDIV was designed for the purpose of addressing security issues in Web application frameworks by extending some of those frameworks to do such things as check of non editable data integrity and perform validations for editable data. Read about potential security problems and how HDIV attempts to address those problems. (July 30, Article)

---

Free Book PDF Download: Mastering EJB Third Edition

Mastering EJB was one of the original and most influential EJB books in the industry. Mastering EJB III now returns with two new expert co-authors, updated for EJB 2.1 and 30% new chapters including security, integration, best practices, open source, and more.
(Book PDF Download)

---

Application Server Matrix

The Application Server Matrix is a detailed listing of J2EE vendors and their application server products, with information on latest version numbers, J2EE spec support and licensing, pricing, platform support, and links to product downloads and reviews.
(Application Server Comparison Matrix)