Frank Sommers has written a tutorial on using JAX-RPC 2.0 for Artima, entitled "Three Minutes to a Web Service," which discusses how JAX-RPC 2.0 uses J2SE5's annotations to generate a web service from Java source.

The article walks through the five steps to deploying a service, bundling the last two steps into one:

• Writing the class
• Generating the JAX-RPC artifacts (such as WSDL, etc)
• Packaging into a .WAR file
• Modification with the wsdeploy tool
• Deployment into an application server

Since the article shows you all of the artifacts generated as well as the deployment descriptors involved, it looks like it might actually take more than three minutes to deploy a web service, unless you use a tool to do most of it.

However, compared to previous mechanisms for generating services, it certainly looks more convenient.

What do you think? Is this a better way than what you've used for web services so far? Is it more testable, or reliable? Is it faster than what you use today?

I find that starting with a doc/literal WSDL and then generating the Java artifacts from that leads to the most interoperability. I've had a lot of difficulty using a generated WSDL from a service endpoint interface (Java interface) with the .NET platform. Writing a doc/literal WSDL from scratch using the "wrapped convention" usually leads to the most interoperability between Java and .NET.

I find that starting with a doc/literal WSDL and then generating the Java artifacts from that leads to the most interoperability.

I cannot agree more. RPC/literal has given us a lot of headaches. Another issue I would like to have resolved is how to enforce XSD data validation into the generated WSDL.

General tips for writing interoperable web services:

* Always use document/literal instead of rpc/literal style

* Always use document/literal "wrapped convention" for both operation parameters and operation return values

* .NET supports both unwrapped/wrapped array convention; can use either one and still be interoperable

* Avoid using the "nillable" attribute when defining types; instead use minOccurs="0"

* Use one-way operations instead of request/response if an operation has void return type

* Store common WSDL data types in a separate XML schema document and import the schema in the WSDL file (use xsd:import and not wsdl:import)

* Start with WSDL first as opposed to Java interface to achieve most interoperability

* Use proper namespaces when writing elements of a WSDL, such as xsd:complexType, wsdl:message, xsd:import, etc.

* Use Mindreef's SOAPscope tool to make sure that a WSDL conforms to the WS-I Basic Profile 1.1 standard

Related links:

Wrapped convetion blog entry by Anne Thomas Manes:
http://atmanes.blogspot.com/2005/03/wrapped-documentliteral-convention.html

Apache Axis and .NET interoperable notes:
http://wiki.apache.org/ws/FrontPage/Axis/DotNetInterop?highlight=%28dotnet%29
http://wiki.apache.org/ws/DotNetInteropArrays

General tips for writing interoperable web services:

Looking at the article, it appears that JAX-RPC 2.0 is following many of these best practices:

* Always use document/literal instead of rpc/literal style

* Avoid using the "nillable" attribute when defining types; instead use minOccurs="0"

* Store common WSDL data types in a separate XML schema document and import the schema in the WSDL file (use xsd:import and not wsdl:import)

* Use proper namespaces when writing elements of a WSDL, such as xsd:complexType, wsdl:message, xsd:import, etc.

I am not a particular fan of JAX-RPC, or SOAP in general, but from what I can see in the article, JAX-RPC is moving in the right direction. Maybe we can relax this rule in the future, at least for simple services:

* Start with WSDL first as opposed to Java interface to achieve most interoperability

I find that starting with a doc/literal WSDL and then generating the Java artifacts from that leads to the most interoperability.

I cannot agree more. RPC/literal has given us a lot of headaches. Another issue I would like to have resolved is how to enforce XSD data validation into the generated WSDL.

that's an interesting comment, though I'm not sure I'd agree. for development environment, it makes sense to validate the data, but for production, I find it better to turn off validation. the reason might be flawed, but in production, I would rather the software keep working and send me an email. this way, if a partner pushes a new schema to their production and forgets to tell me, the code can keep working. this is true in cases where new elements are added, but not where the data format changes drastically or elements are removed.

peter

Interesting timing. Right now, I am looking at a paper that is trying to prove that the JAX-RPC approach to building web services is fundamentally flawed.
See it here: http://www.1060.org/blogxter/entry?publicid=FA0DC57CFB40FB1F2F9EE919DA6BACEF

Over a decade has been spent trying create robust mappings between records in relational databases and language-level objects, and there is still no sign of an ideal solution.

I swear there's JPOX/JDO, Hibernate, and Toplink that all provide reasonable, and give the impedence mismatch perhaps the ideal solutions to the O/R problem. Pretty soon we'll get EJB3 Persistence and if you'd believe the JCP automatons this will be the ideal solution.

Alpine will make no attempt to map between XML and custom Java classes, instead providing access to the SOAP messages using modern XML support libraries, which make it easy to navigate an XML document. By avoiding O/X mapping we greatly decrease the volume and complexity of our code.

and increase the volume and complexity of mine...

Out of the lab, and into the business world - I need to connect a C++ application to my Siebel application and transfer data - I'll be choosing Document/Literal SOAP which has running implementations from multiple vendors.

When/if the Alpine framework becomes available, maybe it will be interesting - now I've got to be productive.

This is a very interesting paper. It makes some points against JAX-RPC mapping that I run into while building a couple of web services with JAX-RPC and IBM WSAD.

Small changes in the schema lead to regeneration of the code, not all constructs were supported that are valid within XSD/WSDL and no validation is performed (except of course the type mapping).

Looking back, I do not like the JAX-RPC model for building interoperable web services.

An approach I am trying out now is the scripted approach, with ECMA-script for XML (E4X).

Here is a related blog on based on my experience with Web services meta data and EJB 3.0

Does Metadata annotations make SOA Development easier with J2EE?

regards
Debu Panda
Oracle

I agree with your point on interoperability. And even in a Java-To-Java Web Service there's an important performance reason to use document-literal or RPC-literal: RPC encoded does not scale.

See:

http://www-106.ibm.com/developerworks/webservices/library/ws-soapenc/

-Frank

I totally agree with the article in that Annotations make the job of writing a web service a lot easier, and more importantly portable. For portability and simplicity the annotations should be used as a tool; but just because it is simple to put together a web service it doesn’t mean it is where you start defining your service.

A web service should be viewed as a *service* which means it has to have a meaningful and supportable interface. To put together a few java objects and call them a web service is essentially creating a nightmare for yourself "in three minutes". To define a service you first need to make sure you have all the business justification and possible security issues that has to go into exposing a service figured out. Then to create a service you have to think about your service use cases and treat the interface as a standards committee defines specification. The operations at the service interface and the documents that are passed back and forth have to be clearly defined as portable XML documents. Sure you can take the “opportunistic” approach and expose your classes (that were not originally designed as a service) as web services, but soon you have versioning and incompatibility problems for the service interface.

I have been working on Beehive (currently in Apache incubator) project’s Web Services Metadata (WSM) module that I think solves this problem. It uses annotation and XMLBeans (in Apache) to implement web services using Axis 1.2 (which is JaxRPC 1.1 compliant stack). Once the schemas are defined, with XMLBeans you can generate the Java types, and with Annotations you can implement your portable web service which runs on Axis today. You can graduate the Services to other stacks that support 181 annotations later. You can find out more on this project in http://incubator.apache.org/beehive/


Daryoush

Well, this way of deploying a web service from a class seem to me not very straigthfull. In the default mode, deploying a web service should be as easy as anotate a class with @webservice and nothing more !
In a default mode, every artifact (wsdl, mapping file) should be generated (in memory) at runtime when the class is deployed.

In the default mode, deploying a web service should be as easy as anotate a class with @webservice and nothing more !

THis is pretty much what JSR 181 specifies. You need @webservice on your class, and @webmethod for every method that should be on your webservice. By default methods are not included on your webservice.

In a default mode, every artifact (wsdl, mapping file) should be generated (in memory) at runtime when the class is deployed.

Java 1.5 annotations are in class files, so a web service stack can extract the annotations and configure itself. There is one minor issue with it, the JSR 181 specifies that by default the WSDL paramters are named after the method argument names(there are annotations to change the name). Unfortunately, there isn’t an easy way to find out parameters names from a method as the name of the parameters get lost in the class file.

I agree with you that all the developer must see is the annotation of the classes and the magic happens behind the cover to build the web services.

Daryoush

In addition the the previous comments there are two things I don't like:

1. Exposing a java class as a webservice. Is this good programming practise? Where is the interface?

2. Importing javax.jws.WebService in an service implementation\interface makes your ties your service definition already to the way it will be exported. These things should not be mixed. What if I also want to export this service using EJB, REST, Burlab, Hessian. I.M.O. the service implementation and the way it is exported should not be mixed.

In addition the the previous comments there are two things I don't like:1. Exposing a java class as a webservice. Is this good programming practise? Where is the interface?

I pretty agree with you, It's generaly a good pratice to devellop by interface. But for a web service, this is not necessary as the client won't use this interface but generate one from WSDL (client is server technologie agnostic).

2. Importing javax.jws.WebService in an service implementation\interface makes your ties your service definition already to the way it will be exported. These things should not be mixed. What if I also want to export this service using EJB, REST, Burlab, Hessian. I.M.O. the service implementation and the way it is exported should not be mixed.

I'm agree too, but it's a problem due to annotations not web-service specific (it's the same problem for EJB3).
I.M.O, most of time, annotations introduce a concept flaw. For exemple, in EJB3 your persistant POJO (say a Customer) carry SQL mapping informations. Those informations are exposed to the presentation layer when rendering those POJOs (displaying all the Customers).
Anyway, even if this design is not clean, i must admit that annotations are a very productive and simple way to accomplish many things.
I.M.H.O the cleanest way do deploy a web service is just to mention a class name somewhere (in web.wxm, in spring context, ....). By default :
- no need to specify an interface
- all the public method are exposed "as meb-method"

Jerome, I love the idea of exposing a class via Spring context or web.xml file.

I've been told that exporting web services in .net is ridiculously easy. While I don't want to go over to the dark side, it's hard to explain why things have to be so damn complicated even for extremely simple functionality.

Check out XFire (http://xfire.codehaus.org). It has native support for Spring using the RemoteExporter mechanism. See http://xfire.codehaus.org/Spring for more details.

Thanks for the link. I've toke a look a this. It looks really promising. I think that's will be the way for dealing with web-service in J2EE.

Jerome, I love the idea of exposing a class via Spring context or web.xml file.I've been told that exporting web services in .net is ridiculously easy. While I don't want to go over to the dark side, it's hard to explain why things have to be so damn complicated even for extremely simple functionality.

having used .NET webservices, it is very easy if you're only talking to .NET webservices. Once you start integrating with other systems, it's about the same. Using annotations is a nice improvement, though I would still create an interface and annotate the interface instead of a java bean directly.

peter

I've played a little with the XFire support a while back when Spring support still was in the sandbox. It is really easy to use: you have your webservice setup in just a few minutes, just export your java interface in your XFire-Spring documentation. And .... you don't need a full blown J2EE container, tomcat will do. Of course for high-end enterprise usage we will need things like ws-security etc. Still, my compliments to Dan, Arjen and others of the XFire team!

I didn't like the usage of contructor injection for configuration but I'm not sure if that is still needed in the current version.