contract-first : WSDL vs Java interface

[aerosteak]

Hello,

I am starting to work with web Service. I just read the SpringWS Tutorial and I totally agree with the contract-first and the data-driven communication concept.

Here is my question: why use WSDL when you can convert any Java Interface and Bean into a WebServices?

If a tool gives you the possibility to move from xml to java (and vice-versa), why not stay with a java interface?


To quote Rod Johnson: ‘…the Java interface is a contract…’.


What are the pitfalls of using this technique (other than being too easy to change the contract)?


I think this code could achieve the same goal as the Tutorial:

interface HumanResources {
public void doRequest (HolidayRequest request);
}

Class HolidayRequest {
..
}

[Arjen Poutsma]

I am starting to work with web Service. I just read the SpringWS Tutorial and I totally agree with the contract-first and the data-driven communication concept.

Here is my question: why use WSDL when you can convert any Java Interface and Bean into a WebServices?

If a tool gives you the possibility to move from xml to java (and vice-versa), why not stay with a java interface?


To quote Rod Johnson: ‘…the Java interface is a contract…’.


What are the pitfalls of using this technique (other than being too easy to change the contract)?

Good question.

Firstly, a WSDL defines an XML API interface. Web services are about XML. The fact that you're using Java is just an implementation detail, and if the client actually cares about the fact that Java is used on the server-side, then Web services are not your best choice.

Secondly, XML, especially the schema language (XSD), is a different language then Java:

• XML Schema is richer than Java. XSD has things like dates, which represent a year, month, and day. Java has java.util.Date and java.util.Calendar, both of which represent date times. Now when a client sends you 2007-02-07, this will be transformed into 2007-02-07:00:00.000 (i.e. 2nd Februari at midnight). Not the same thing, especially if the time is also manipulated because of timezones!
• Incompatible naming. Some Java names are invalid XSD names and vice-versa.
• xsd:enumeration. Even in Java 5, the xsd:enumeration is not the same as a Java enumeration.
• Unserializable types. XSD doesn't have a map datatype. So what happens if your Java interface returns a HashMap. You can try to marshal your Java map into XML, which can actually work, but when you unmarshal the XML on the client-side, you will probably not end up with the HashMap you started out with.
• Independent namespaces XSD allows you to use different namespaces for elements, attributes, etc. This is hard to express in Java.

These issues, and more, can be found in Rethinking the Java SOAP Stack.

Thirdly, it is a good practice to have a loose coupling between WSDL and Java implementation. This helps with things like Web service versioning, for instance.

Fourthly, there are multiple ways to create a WSDL from a Java interface. This means that you might start out with one WSDL, and the moment you upgrade or change your SOAP stack, you will end up with a different version. I've seen this occur at multiple clients, and it really is nasty.

Finally, using a Java interface as the contract makes it tempting to expose your inner domain objects. The moment you make them part of your public contract, you're not able to change them anymore. WSDL-first makes it easier to separate schema objects from domain objects. They might start out the same, but they can evolve independantly. "Don't spill your guts!", is what I always say in my presentations.

To summarize: yes, a Java interface is a contract as well, but for a Java API. If you want to offer an XML api, you're better off defining it in XML, ergo: WSDL.

[aerosteak]

Thank you very much for the article, it was the information I was looking for. The problem is clearer now.

We are currently in the process of defining a SAO strategy. The contract-first vs contract-last issues have a major impact on the development.

Exposing a Java Interface as a WebService with JAX-WS can take a few minutes but doing the same with XML/XSD/WSDL would require a lot more work and knowledge.

The XML approached will bring more flexibility but at a big price.

XSD and WSDL are extensively verbose and hard to master.

I was surprise to see in the article : “Perhaps WSDL is not the appropriate language for describing SOAP services”

I am surprise to see, in year 2007 and after all these Committee and JSR’s, that defining an ‘Interface’ (in the sense of implementation independent signature of the service) is still a challenge.

Do you know any good tools to work with WSDL?

[Arjen Poutsma]

Do you know any good tools to work with WSDL?

Well, if you use Spring-WS, and you follow the standard approach (i.e. Request message ends with Request, and Response ends with Response), you don't have to write the WSDL yourself, but SWS will do it for you based on the XSD! How's that for a tool!

Basically, it takes the approach taken in this article of mine, though it doesn't use XSLT, but Java. Look in the echo example to see how it is used.

And with regard to WSDL not being the best language to express Web services, I agree. SSDL seems much better, but it's not the standard.