SOAP Web Services have a well established role in the enterprise, but aside from the many benefits of the WS-* standards, SOAP and XML also carry additional baggage for developers. Consequently, REST Web Services are gaining tremendous popularity within the developer community. This session will begin by comparing and contrasting the basic concepts of both SOAP and REST Web Services. Building on that foundation, Sam Brannen will show attendees how to implement SOAP-based applications using Spring-WS 2.0. He will then demonstrate how to build a similar REST-ful application using Spring MVC 3.0. The session will conclude with an in-depth look at both server-side and client-side development as well as efficient integration testing of Web Services using the Spring Framework.

1. Spring Web Services:
SOAP vs. REST
Sam Brannen
Swi+mind GmbH

2. Speaker Profile
• Senior So+ware Consultant – Swi+mind GmbH
• Java developer with 13+ years' experience
• Spring Framework Core Developer
– Author of the Spring TestContext Framework
• Previous SpringSource dm Server™ developer
• Regular speaker at conferences on Spring, dm
Server, Java, OSGi, and tesOng
• Lead author of Spring in a Nutshell;
chief technical reviewer for Spring Recipes

3. Agenda
• Web Services Concepts
• Spring Events ApplicaOon
• Spring‐WS
• Spring REST
• Server‐side
• Client‐side
• Q&A

4. Web Services

5. Concepts
• Client / Server architecture over the Web
– Server exposes Services
– Client sends a Request to the Server
• for a specific exposed Service
• with a Payload to be processed by the Service
– Service processes the Request and returns a
Response

6. Marshalling and Unmarshalling
• Marshalling: Object  external format
• Unmarshalling: external format  Object
• a request or response contains a payload
– o+en in the form of an XML document
– may also be binary, JSON, etc.
• applicaOon code has its own domain model
– may not map directly to format of payload

7. Spring Events Applica?on

8. Introducing Spring Events
• Simple POJO domain model: Event
• TransacOonal service layer
• Hibernate repository layer
– With an in‐memory HSQL database
• Spring @MVC presentaOon layer
– RESTful @Controller
• Spring‐WS @Endpoint

9. Demo
Spring Events ApplicaOon

10. SOAP Web Services

11. What is Spring‐WS?
Spring Web Services aims to facilitate
contract‐first SOAP service development,
allowing for the creaAon of flexible web
services using one of the many ways to
manipulate XML payloads.
(Spring‐WS Web site)

12. What is SOAP?
• Simple Object Access Protocol
– Protocol for exchanging informaOon via Web
Services
– Uses XML as its message format
– Typically over HTTP
• Structure
– Envelope
– Header
– Body (a.k.a., payload)
– Document literal

13. Contract Last
• Define API in programming language (e.g., Java)
• Use tools to generate XSDs and WSDL from code
• Pros
– easy, no‐brainer for developers
• Cons
– horribly fragile
– any change to code breaks previously published
contract
– clients must be updated

14. Contract First
• Define public API to services via XSD schemas
first
– one request and response per exposed service
– generate WSDL from XSDs using convenOons for
port types, etc.
• potenOally auto‐generated
– generate Java code from XSDs (e.g., JAXB2)
– create Java mapping code manually
– or use XPath, etc. to parse XML directly

15. REST Web Services

16. What is Spring REST?
• RESTful Web Services built on top of Spring
@MVC
• Combines nicely with exisOng @MVC code
• Low learning curve for developers familiar
with Spring @MVC
• Supports mulOple marshalling technologies
suitable for web applicaOons (e.g., JSON)
• Spring REST != JAX‐RS

17. What is REST?
• REpresentaOonal State Transfer
• HTTP Protocol
– Standard
– Ubiquitous
– Scalable
• Stateless
• Focuses on resources
– Nouns and Verbs

18. Nouns, Verbs, & Errors
• Nouns
– Resources that you want to interact with
• Verbs
– What you can do with a resource
• POST: create new resource
• GET: get single resource or a list of resources
• PUT: update resource
• DELETE: delete resource
• Error handling
– Standard HTTP response codes

19. RESTful URLs
• POST
– hip://example.com/events
• GET
– hip://example.com/events
– hip://example.com/events/1
• PUT
– hip://example.com/events/1
• DELETE
– hip://example.com/events/1

20. Server‐side

21. Spring‐WS on the Server
• Bootstrapped in web.xml with
MessageDispatcherServlet
• <sws:annotaOon‐driven /> enables
@Endpoint mappings (a la @Controller)
• @PayloadRoot maps handler methods
• @RequestPayload maps payload to method
parameter
• @ResponsePayload maps return value to
response payload

22. GetEventEndpoint (1/2)
@Endpoint
public class GetEventEndpoint {
private static final String NAMESPACE_URI =
"http://example.com/schemas";
private final EventService eventService;
@Autowired
public GetEventEndpoint(EventService eventService) {
this.eventService = eventService;
}

23. GetEventEndpoint (2/2)
@PayloadRoot(localPart="GetEventRequest",
namespace=NAMESPACE_URI)
@ResponsePayload
public GetEventResponse getEvent(
@RequestPayload GetEventRequest request)
throws Exception {
Event event =
eventService.findById(request.getId().longValue());
return toGetEventResponse(event);
}

24. Spring REST on the Server
• REST Web Service endpoints are
@Controllers
– @RequestMapping: maps to handler methods
– @RequestBody: payload of request
– @ResponseBody: payload of response
– @ResponseStatus: set HTTP response code
– @PathVariable and UriTemplate
• For mapping and creaOng RESTful URIs
• AutomaOc marshalling of payloads
• Content negoOaOon

25. EventController (1/4)
@RequestMapping("/events")
@Controller
public class EventController {
protected final EventService eventService;
@Autowired
public EventController(EventService eventService) {
this.eventService = eventService;
}

26. EventController (2/4)
@RequestMapping(method = GET)
@ResponseBody
public List<Event> retrieveAllEvents() {
return eventService.findAllEvents();
}
@RequestMapping(value = "/{id}", method = GET)
@ResponseBody
public Event retrieveEvent(@PathVariable Long id) {
return eventService.findById(id);
}

27. EventController (3/4)
@RequestMapping(method = POST)
@ResponseStatus(HttpStatus.CREATED)
public void createEvent(@RequestBody Event postedEvent,
HttpServletRequest request,
HttpServletResponse response) {
Event savedEvent = eventService.save(postedEvent);
String newLocation =
buildNewLocation(request, savedEvent.getId());
response.setHeader("Location", newLocation);
}

28. EventController (4/4)
@RequestMapping(value = "/{id}", method = DELETE)
@ResponseStatus(HttpStatus.NO_CONTENT)
public void deleteEvent(@PathVariable Long id) {
eventService.deleteById(id);
}
private String buildNewLocation(HttpServletRequest request,
Long id) {
String url = request.getRequestURL()
.append("/{id}").toString();
UriTemplate uriTemplate = new UriTemplate(url);
return uriTemplate.expand(id).toASCIIString();
}

29. HiddenHipMethodFilter
• Web browsers typically only support GET and POST
• HiddenHipMethodFilter
– provides support for PUT and DELETE requests
from web browsers
– transparently converts POST requests with
hidden _method parameter
• Configured in web.xml
• Can be used in conjuncOon with Spring’s JSP
form tag library

30. URI Templates in JSPs
• Use the <spring> tag library to construct dynamic
URI templates in JSPs
• Similar to the JSP core tag library support for
building URLs with parameters
<spring:url var="jsonUrl" value="/rest/events/{id}">
<spring:param name="id" value="${event.id}" />
</spring:url>

31. Client‐side

32. WebServiceTemplate
• Interact with SOAP Web Services as a client
• Supports callbacks as well as automaOc
marshalling and unmarshalling of payloads
– sendAndReceive(…)
– marshalSendAndReceive(…)
– etc.

33. EventsSoapClientTest (1/2)
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
public class EventsSoapClientTest {
@Autowired
private WebServiceTemplate webServiceTemplate;
<oxm:jaxb2-marshaller id="marshaller”
contextPath="com.swiftmind.samples.events.web.schema" />
<bean id="webServiceTemplate"
class="org.springframework.ws.client.core.WebServiceTemplate”
p:marshaller-ref="marshaller" p:unmarshaller-ref="marshaller" />

34. EventsSoapClientTest (2/2)
@Test
public void getEventRequest() {
String url = "http://localhost:8080/spring/soap";
GetEventRequest request = new GetEventRequest();
request.setId(BigInteger.valueOf(5L));
GetEventResponse response = (GetEventResponse)
webServiceTemplate.marshalSendAndReceive(url, request);
assertNotNull(response);
assertEquals("Spring I/O in Madrid",
response.getEventData().getDescription());
}

35. RestTemplate
• Interact with any REST Web Services
– not limited to Spring REST services
• Supports URI templates and automaOc
marshalling and unmarshalling of payloads
– postForLocaOon(…)
– postForObject(…)
– getForObject(…)
– delete(…)
– put(…)
– etc.

36. EventsRestClient (1/3)
public class EventsRestClient {
private final RestTemplate restTemplate =
new RestTemplate();
private String url;
public URI createEvent(String name) {
Event event = new Event();
event.setName(name);
return restTemplate.postForLocation(url, event);
}

37. EventsRestClient (2/3)
public void deleteEventByLocation(URI location) {
restTemplate.delete(location);
}
public void deleteEventById(Long id) {
String deletionUrl = url + "/{id}";
restTemplate.delete(deletionUrl, id);
}

38. EventsRestClient (3/3)
public void retrieveEvent(URI location) {
Event event = restTemplate.getForObject(location,
Event.class);
}
public void retrieveAllEvents() {
Event[] events = restTemplate.getForObject(url,
Event[].class);
}

39. Demo
Spring SOAP Web Services

40. Demo
Spring REST Web Services

41. Further Resources
• Spring Framework
– Including Spring REST
– hip://springframework.org
• Spring‐WS
– hip://staOc.springsource.org/spring‐ws/sites/2.0/
• Generate XSD from XML
– hip://bit.ly/fLI1Bt

42. Q&A
Sam Brannen
sam.brannen [at] swi+mind [dot] com
hip://www.swi+mind.com
hip://twiier.com/sam_brannen
“Spring in a Nutshell”
hip://oreilly.com/catalog/9780596801946
available from O’Reilly in 2011