jump to navigation

Creating a Web Service with Spring-WS July 16, 2008

Posted by Phill in Other Stuff, Spring.
Tags: , , , , ,
comments closed

Recently, I’ve had to use Spring-WS to expose a couple of web services. I’d previously exposed web services using CXF (or XFire as it was then), but that worked a bit differently: you defined the beans you wanted to expose as Web Services, and XFire would generate all the WSDL for you.

I wanted to try out contract-first web service development, hence me using Spring-WS. (There are a variety of good reasons to use contract-first development, rather than generating your interface from Java.)

Anyway, to cut a long story short, here are a few brief notes about my experiences, hopefully this will help out anyone else who wants to start developing in Spring-WS 🙂

  • Before you even start reading through the Spring-WS documentation, read up about XSD. Seriously, if you don’t know XSD, you will need to. Even a basic understanding will help greatly. This document by the W3C is an excellent place to start.
  • The Spring-WS Tutorial isn’t very helpful, in that it only defines a web service which has a request (i.e., no response is required). If you want the Web Service to have a response, you need to also include a “{Name}Response” type in your XSD. In other words, if their example should be modified to include a response to a HolidayRequest, you should include a HolidayResponse element.
  • I used JAXB as an O/X mapper. It has an Ant task which will generate your Java classes from an XSD, which I found very useful. It’s also dead easy to use with Spring-WS.
  • If you’re not using Spring MVC, you’ll need to set up a MessageDispatcherServlet. I bound mine to the path /services/* – however, there are a couple of ‘gotchas’ here:
  1. You’ll probably want to set the transformWsdlLocations parameter to ‘true’, so you can specify the web service path as a relative URL.
  2. The servlet, being a Spring MVC style servlet, looks for an application context .xml file in /WEB-INF/{servlet-name}-servlet.xml. As far as I know, you must include this. It’s not really a problem because it helps separate out concerns (i.e. defining all your Web Service beans in one place) – and also, you can reference all your beans defined elsewhere. However, it’s just something to be aware of.
  3. Remember I said I bound my servlet to /services/*? When you define your endpoints, you must include that prefix in the endpoint. So, if the URL to your service is /ContextPath/services/MyService/, your “locationUri” property of the endpoint will be /services/MyService/. Not /MyService/. It took me a while to figure that out!
  • Finally, you’ll need several beans to define a Web Service. Although you can get this from the Spring-WS documentation, this is a list in the one place:
    • A Wsdl Definition (such as DefaultWsdl11Definition) – which will expose your WSDL.
    • An XSD Schema definition (such as SimpleXsdSchema) – if you’re automatically generating WSDL from your XSD.
    • An endpoint mapping (such as PayloadRootQNameEndpointMapping), which will map from the incoming requests onto your endpoints.
    • Any endpoints you want to have setup, i.e. one per web service you want to expose
    • If you’re using a Marshaller (such as JAXB), you will also need the marshaller / unmarshaller configured, for example Jaxb2Marshaller.

*phew* I think that’s just about everything.

I realise all that is probably not very clear, it’s just a few notes from the little issues I’ve run into over the past few days trying to get the web service to work. In time I might get around to organising it into a more coherent tutorial 🙂