February 28, 2021
Hot Topics:

Get RESTful with Spring 3.0

  • By Michael Pilone
  • Send Email »
  • More Articles »

Service oriented architectures and simple service-based mashups have become very popular in the past few years as businesses became more agile and Web 2.0 sites began to integrate more data from more places. Frameworks such as Axis and Apache CFX, as well as Java standards such as JAX-WS and JAX-RS, have sprung up to support these types of applications by exposing services through various lightweight client/server protocols. In August of 2007, the Spring community added Spring Web Services (Spring-WS) 1.0 to the mix, which added Simple Object Access Protocol (SOAP)-based web service integrations to Spring Framework applications.

Fast forward to today, and Web 2.0 mashups are more popular than ever, increasing the demand for easier ways to integrate web applications with dynamic backend data. All of the specifications and promises of SOAP-based web services haven't fully panned out, and developers are looking for better ways to consume services in JavaScript- and Flash-based applications through the browser-supported XmlHttpRequest object.

Unfortunately, your organization more than likely spent the past few years building out a SOAP API that you don't want to (or can't afford to) abandon. This article walks through the implementation of a REST-like API (see Sidebar 1. 'REST-like' vs. REST Service) that fully leverages your existing SOAP-based services using the new features of Spring 3.0 in order to get a more Ajax-friendly API quickly. You should have a basic understanding of Spring-WS and Spring's MVC pattern, as well as the Java API for XML Binding (JAXB), before continuing. However, in most cases, you probably already have these technologies deployed in your system.

Background for the Example

SOAP is an XML-based protocol normally based on HTTP as the transport mechanism. SOAP web services can be very powerful when combined with good language support, as you find in Java (through various third-party libraries) and .NET. However, if a language doesn't provide support, exposing or consuming a SOAP service can be a slow, painful, and error-prone experience for the developer. This is commonly the case with scripting languages such as JavaScript and Python. While you can do it, it isn't an ideal approach.

As a good web services developer, you most likely defined your existing SOAP services using XML schema and the web service definition language (WSDL). This contract-first approach can be very valuable in clearly defining your API and providing documentation to end users. This article will show you how to use these API definitions to expose a REST-like API that is easier to consume from a JavaScript application, while not abandoning the benefits offered by the XML schema and WSDL. Figure 1 shows the final set of APIs that will expose the demo business service.

Figure 1. Final Set of APIs that Will Expose the Demo Business Service:
These are the APIs that will expose the internal weather service business logic to clients. The same XML Schema is used to define the messages to all three APIs.

The example in this article will use only the HTTP POST operation for requests. It will also use the existing WSDL-defined operation names rather than introduce new resource names. To make the services easier for clients to consume, the SOAP API will be complimented with both the JavaScript object notation (JSON) and simple XML APIs.

That's enough background; it's time to write some services.

The Existing Web Service Endpoint

To begin, you need an existing SOAP-based web service that you will ultimately expose as a REST-like service that supports both the JSON and basic XML formats. With Spring-WS, the demo weather service would be defined in a WSDL with a supporting XML schema as in Listing 1 and Listing 2. You can see that the service supports three operations:
  • convertTemperature
  • saveWeatherUpdate
  • getWeatherReport

Listing 3 shows how the web service operations are then implemented in an endpoint, which uses the Spring-WS annotations @EndPoint and @PayloadRoot to connect the WSDL messages to specific operations. The parameter objects to each implemented operation are generated using the XJC command of JAXB from the XML Schema of domain objects for this service, which allows Spring-WS to automatically unmarshal the SOAP request into a Java object and pass it to the endpoint's operation. Automatic marshalling and unmarshalling greatly reduce the amount of code you need to write and maintain.

The web service endpoint delegates the actual business logic of each operation out to the common business tier WeatherService shown in Listing 4. If your application design doesn't cleanly separate the web service tier from the business tier, you may need to do a little refactoring before trying to support an additional API.

Finally, you tie all of these pieces together through the web.xml servlet definition in Listing 5 and the WeatherSoapService-servlet.xml Spring bean configuration file in Listing 6.

Fully defining and explaining Spring-WS and Spring MVC is beyond the scope of this article. If you're confused at this point, you may need to brush up on those frameworks first and then come back. The focus now is to take this existing, three-operation service and make it available as a REST-like service that supports JSON and simple XML messages.

Page 1 of 3

This article was originally published on December 23, 2009

Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Thanks for your registration, follow us on our social networks to keep up-to-date