Sometimes, my I21 coworker and friend Alef Arendsen has a very good idea. On Friday the 11th of November, he is organizing a get-together for Dutch Java developers. It will be held near Dam square, in a very authentic “jenever proeverij” (Wijnand Fockink).
I’ll be there: I’ll do anything for a free beer :-).
In the previous post, I introduced the design goals behind the Spring Web Services SOAP framework. In this post, I describe how one would go about implementing a Web service with Spring-WS. Please note that any code shown in this post is non-final, and only reflects the current design we have.
Before you implement your service, there are some design choices you need to make. These are important choices, but you can reuse these for every service.
First, there is the choice whether you want to implement a service endpoint in a single class, or in separate classes. Traditionally, Web services are just single classes, with every method representing an operation. This can result in large classes, and thus code smell. Within Spring-WS, there is the option to implement a service operation as separate class, just as you would implement a single Controller class when using a Web UI framework such as Spring-MVC. If you prefer to use a single class, however, that is also possible, but we will cover the single-class case in this post.
Within a service endpoint, you have to choose whether you are interested in the complete message, or just the contents of the message body (i.e. the message payload). If you want the complete message, you implement the MessageEndpoint interface, which contains just one method:
SOAPMessage invoke(SOAPMessage request) throws Exception;
The SOAPMessage used here is the standard, SAAJ javax.xml.soap.SOAPMessage.
However, it is much more likely that you are interested in the message payload, because that contains the interesting bits.
If you want the message payload, you implement the Spring-WS interface PayloadEndpoint, which also contains one method:
Source invoke(Source request) throws Exception;
The Source used here is a javax.xml.transform.Source, a XML input abstraction. The PayloadEndpoint interface has convenience subclasses which allow you to use DOM, SAX, or StAX directly1
Within your endpoint, you read the XML, invoke a few business methods on your middle tier, and formulate a reply, if desired. Presto!
Of course, you can use Object-XML mapping in your endpoint if you want to, making the handling of XML somewhat easier. We’ll cover the O/X Mapping support of Spring-WS in a future post, but suffice it to say that Spring-WS offers an abstraction which makes it easier to switch from one OXM implementation to another. Also, the exceptions thrown by these marshalling frameworks are all converted to runtime exceptions, and unified to a single hierarchy, just like in Spring’s data access and ORM support.
When the endpoint is done, you need to decide how it is mapped to a request. This topic is also reserved for a future post, but basically, all standard mapping techniques (URL-based, SOAPAction-based, and message-based), are supported. You can even write your own mapping logic if nothing suits you.
<hr/>
1 - Both MessageEndpoint and PayloadEndpoint can be compared with JAX-WS, which defines the Provider interface. By setting the enumerated value for a @ServiceMode annotation on the generic Provider, you can accomplish the same thing, though it’s a bit too Java 5-heavy for my taste.
Last week, in my presentation at the NL-JUG JFall, I introduced the Spring Web Services framework, a new major module for the Spring framework. You can download the slides from the presentation here.
I am sure there are a lot of people with questions about this framework. In a series of posts, I will try to formulate an answer to these. This first post is a generic introduction into the Design Goals of Spring-WS, more spicy stuff will come later.
We believe that Web Services deserve a proper place in an application architecture. Too often, Web Services exist as an afterthought in the application architecture, mostly because existing Java business interfaces are SOAPified by placing them in a Web Service container. We think that developing Web Services, both now and in the future, require careful thought and consideration, enough to justify a framework especially created for this purpose.
We do not believe there is any point in creating another black-box Web services container which does not allow a developer to customize service deployment and development. Instead, we believe in a transparent framework which offers customizability on all fronts.
Spring’s powerful features like Inversion of Control and Aspect-Oriented Programming make it a solid ground for an application framework. We plan to use Spring where possible, both as a framework and as a source of inspiration.
With relative little effort, it should be possible to swap one piece of the framework for another. For instance, it should be possible to replace one Object/XML-mapping framework with another. Spring, in combination with proper use of Java interfaces, will help us here.
We believe that the future of Web Services lies in SOAP. While other standards and implementations also focus on REST-like services, we believe that there is little value in creating a framework for these kind of Web Services. REST services seem to have very little common functionality that cannot already be captured with Java classes like the HttpServlet.
This does not mean that developers cannot use facilities provided by Spring-WS. For instance, the Object-XML Mapping abstraction we have planned can be useful for REST as well as SOAP.
There is little sense in reinventing the wheel. For this reason, we do not plan to create our own security framework, Object/XML-mapping framework, or SOAP mess, and the commercial world.
Customizability comes with a price. We plan to provide defaults where possible, but force the service developer to make a choice where necessary. Our goal is too make Web Service development as simple as possible, but not any simpler.
As I have written previously, RPC-style Web Service development has many disadvantages. We will focus on message-based development instead.
Contract-first Web Service development is considered a best practice. While we plan to facilitate in both contract-first and contract-last development, we should point out the issues that go along with contact-last development.
Keep watching this space for more information…