Channels ▼

Web Development

Best Practices in Spring Web Services and Java

We recently spoke to Arjen Poutsma, a consultant with Interface 21 and the project lead for the Spring Web Services framework, which was released on August 21st after two years of development. Arjen designed the framework with a "contract-first, document driven" development style.

DDJ: Arjen, how does the contract-first, document-driven approach work?

AP: There are two approaches to developing web services in Java. There's the code-first, contract-last approach where you take an existing Java class and you generate a contract out of this, meaning both a WSDL file, which contains the contract, and the schema file, which contains the messages. These two are derivatives of the Java class.

The other approach is to define an XML API, focusing it at what my messages are going to look like, what's the idea for the contract, and then derive my Java code from this. You just use Java as the implementation language. The key thing is the contract, and the benefit is you solve a lot of interoperability issues.

One of the issues with contract-last approach is that the contract can change. Every time you change the Java class, you change the contract. Even if you upgrade your version of the web services framework to another version, the contract might also change. You want it to be as fixed as possible, or if it changes, you want to be in charge of when it changes.

When I started this whole project two years ago, it became clear to me that contract-first was best practice but nobody was doing it because it was pretty hard. The easiest way was to do the code-first approach. With Spring Web Service I tried to make the best practice an easy practice.

Another distinction would be flexibility in handling messages. If you have a WSDL interface and you directly tie that to a particular Java class that has three parameters, when the XML messages come in and they vary a little bit, if the third parameter isn't there, your code won't be invoked. One of the key principles of having a service-oriented architecture is that you're loosely coupled. The more flexible approach that Spring WS takes means you can handle an XML message any way you want to. You can take an XML parsing approach using any of the XML APIs that Java offers, all the DOM APIs, JDOM, and so on. There are also all the faster, streaming APIs like SAX, StAX, or you can use XPath, or even you can do XML marshalling.

When you get into the object/XML impedance mismatch, XML Schema is a particular language and Java is another language, and they don't map one to another. For example, take a Java class of Person with a Spouse parameter, if you take a naive approach and try to convert this into XML, you'll have a deeply recursive condition that has no stop condition. You'll have a Person tag, with a Spouse tag, with another Person tag, and another Spouse tag -- it would never end. So flexibility is the key. You are in control. We try to offer choice so you can handle the XML in any way you want to.

DDJ: How does Spring WS compare to some other web service frameworks already available?

AP:Primarily the explicit focus on contract first. Other projects have contract first support, but it's definitely not their main focus. With Spring WS it is -- there's no way to start from Java.

When I began two years ago, there were a lot of questions about whether we needed [a new framework], whether it provides anything new, but that was before any code was available. Now there thousands of users of Spring-WS, and they like it and defend it. These are people who want to build a web service as a proper part of their architecture, not just as a check-mark feature.

DDJ: How does Spring-WS relate to the other parts of the Spring portfolio, such as the core Spring Framework and Spring MVC?

AP: It's built on the Spring Framework itself. Spring is a very good framework for building an application. The programming model is very similar to the programming model in Spring MVC. You have the role of a Controller in Spring MVC, which takes input parameters from a web request and invokes some kind of business service with those parameters to render a response. You have the same model in Spring-WS. You define an end-point that looks at the incoming XML message using whatever API you want, it invokes a business class or POJO (Plain old Java object), and given the return value from that POJO, it generates a response. It's your choice. Sometimes you want performance, so you want to do it in a streaming fashion. Sometimes you don’t care about performance, but you want flexibility, and one flexible way is to use XPath. It's like a query language for XML, so you just select all the pieces you need. If they're not there you don't get an exception error, you just get some empty results.

There is also tight integration with Spring-Security, the enterprise security framework. By using aspect-oriented technology, you can actually put security constraints on a business method, or on a POJO service. You can say, "whenever you want to invoke this method, you have to be an administrator." Then using plain Spring security, you can authentic with a normal login dialog, and with Spring WS you can also authenticate using ws-security, so you can put the credentials of the user inside the SOAP header. It can authenticate against any LDAP directory or Windows Active Directory for that matter, any kind of single sign-on solution. Because Spring Web Services integrates with Spring Security, we get these features for free.

DDJ: What are the future plans for Spring Web Services?

AP: In the short term, obviously we'll release any 1.0.x bug fixes. In the medium term, we will support multiple transports. Right now we have HTTP transport, but later we'll add SOAP over JMS, SOAP over email, and TCP/IP. We'll also have more integration with Spring 2, including XML namespaces. In the longer term, we're going to see REST support. It makes sense to use REST in certain cases, but we want it to be a first-class citizen. We want to make sure that we get the abstractions right, not to high or too low.

DDJ: Where can readers go for more information?

AP: The Spring Web Services download page. The download contains four examples, from a very simple example -- a minimal, echoing application -- scaling all the way up to a normal enterprise application using Hibernate persistence, and transactionality. It's a complete enterprise application, and people can see how Spring Web Services fits into that.

From there you can also access a tutorial on writing contract-first web services. One other interesting feature, when I talk about WSDL and Schema XSD, it seems like you have to create everything from scratch, but that's not true. In the tutorial, there's a nice process where you start by defining what a message will look like and what you'll expect in the message back. And using a variety of tools you can infer a schema from that. You can tweak the inferred schema and Spring-WS will generate a WSDL file for you.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.