|
Sponsored Links
Resources
Enterprise Java
Research Library
Get Java white papers, product information, case studies and webcasts
|
News
News
News
|
Messages: 25
Messages: 25
Messages: 25
Printer friendly
Printer friendly
Printer friendly
Post reply
Post reply
Post reply
XML
XML
XML
|
 |
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.
|
|
|
Message #229973
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
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
|
|
|
Message #229975
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
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
|
|
|
Message #229976
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Enunciate Your Web Service API
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.
|
|
|
Message #229979
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
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.
|
|
|
Message #229980
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Maven support?
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.
|
|
|
Message #229982
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Maven support?
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.
|
|
|
Message #229983
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Maven support?
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?
|
|
|
Message #229998
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
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.
|
|
|
Message #230011
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
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.
|
|
|
Message #230023
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: 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.
"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.
|
|
|
Message #230027
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Contract first development, dammit !
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.
|
|
|
Message #230028
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: crispy?
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.
|
|
|
Message #230040
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
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...
|
|
|
Message #230045
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Contract first development, dammit !
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.
|
|
|
Message #230137
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
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.
|
|
|
Message #230195
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Contract first development, dammit !
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.
|
|
|
Message #230248
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
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...
<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
|
|
|
Message #230258
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Contract first development, dammit !
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?
|
|
|
Message #230259
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Contract first development, dammit !
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.
|
|
|
Message #230318
Post reply
Post reply
Post reply
Go to top
Go to top
Go to top
|
|
Re: Contract first development, dammit !
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
|
|
|
| New content on TheServerSide.comNew content on TheServerSide.comNew content on TheServerSide.com |
|
|
Reza Rahman continues to explore the features of the proposed JSR 299, Contexts and Dependency Injection for Java EE (CDI). When approved, it promises to be a key feature of Java EE 6.
(January 21, Article)
Ted Neward is an independent consultant specializing in high-scale enterprise systems, and an authority in Java and .NET technologies. He is the author and co-author of several books, including Effective Enterprise Java. At TheServerSide Java Symposium in March, he will be presenting sessions on pragmatic architecture, ECMAScript and Scala.
(January 15, Article)
Now that Oracle is absorbing Sun Microsystems, there mixed views on what should come of the Java Community Process (JCP). While some say Oracle should become the new steward of Java and keep the JCP much as it was, others argue that it may be time to open-source this widespread language.
(November 24, Article)
Reza Rahman explores the features of the proposed JSR 299, Contexts and Dependency Injection for Java EE (CDI). When approved, it promises to be a key feature of Java EE 6.
(November 2, Article)
SAML is an XML-based standard for exchanging authentication and authorization data between security domains. The single most important problem that SAML was created to solve is the Web browser Single Sign-On problem. Many organizations are debating whether to stay with version 1.1 or move to 2.0. This article makes observations about both options.
(September 28, Article)
Joe Ottinger takes a look at how people learn, and applies it to the practice of programming. He notes that understanding how people learn is an essential part of working in a programming team.
(September 22, Article)
Stephen Maryka gave us an article about the Asynchronous Web and posed a number of questions that get examined like an approach to delivering Asynchronous Web capabilities through extensions to existing Java EE technologies.
(July 14, Article)
JavaServer Faces Flex goal is to provide users capability in creating standard Flex components, part of flexSDK which is open sourced through MPL license, as normal JSF components. This article by Ji Hoon Kim will provide an overview of creating a simple multilingual JSF page consisting of JSF Flex tags.
(June 29, Article)
In this session Jeff explores the key characteristics of successful SOA projects. He covers some of the patterns, and anti-patterns, tool sets, and strategies that he himself learned the hard way. Last, he provides a strategy and blueprint for achieving a high likelihood of success in your SOA project.
(June 23, Tech Talk)
Ari Zilka, CTO of Terracotta, Inc., talks about the new features in Terracotta 3.1, announced during JavaOne and available now.
(June 15, Tech Talk)
In this Tech Talk, Josh Long explores an integration challenge using Spring Integration and walks through the implementation, employing and expanding on the basic patterns of Enterprise Application Integration to tie together components into a function integration solution, and then demonstrates how Spring Integration helps address the integration requirements.
(June 15, Tech Talk)
In this Tech Talk, David Geary teaches you: The basics of Google Web Toolkit; How to implement Ajax-enabled applications in Java; Internationalization; Hooking into the browser history mechanism; Remote procedure calls.
(June 4, Tech Talk)
Jon Kern discusses the best architecture/technical solutions and ensure that they are repeated by all developers. By tackling the architecture up-front in a serial manner, subsequent parallel development will be much more manageable and predictable.
(May 28, Tech Talk)
This keynote describes the frustrations of modern knowledge workers in their quest to actually get some work done, and solutions for how to guard yourself against all those distractions. Neal Ford talks about environments, coding, acceleration, automation, and avoiding repetition as ways to defeat the misguided attempts to sap your ability to produce good work.
(May 26, Tech Talk)
Gil demonstrates how new, aggressive uses of already abundant compute capacity by common applications offer competitive value for application designers.
(May 21, Tech Talk)
Chris Keene introduces WaveMaker as a new way to automate the ability to generate Hibernate classes in order to more quickly bring OR mapping into an application.
(May 19, Article)
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)
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)
|
|
