jump to navigation

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

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

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🙂


1. bv - July 19, 2008

it would be great if you have a detailed tutorial..
for people like me, who need to start doing things yesterday, it takes time to read on things and try..

theres no how to – tutorial for spring webservices though..


2. Phill - July 19, 2008

There is a tutorial here:


Which should be good enough to get you started at least!

3. Ben Avery - August 12, 2008

another gotcha not explained in the tutorial is using Spring WS to generate the WSDL for you, using DefaultWsdl11Definition.

this is another program by convention class, which is great when you know what it does, but annoying until then.

e.g. if you want to create the WSDL for a WS called EmployeeSearch which has an input and a response, you’d call the request type EmployeeSearchRequest and EmployeeSearchReponse for the return type, otherwise it won’t be generated.

I love Spring, but would love it more if they paid someone to keep their documentation and tutorials up to date, and sufficiently detailed!

4. Noah Green - January 30, 2009

THANK YOU! The “transformWsdlLocations” item alone was a huge help. You saved me at least a day of work. Why why why was that item not in the Spring tutorial? In fact, why why why doesn’t transformWsdlLocations default to “true” to begin with? (Who would want to hardcode hostnames/absolute paths into their WSDL?)

Truly you are the author of “Spring Web Services: The Missing Manual.” Thanks again.

Chris - September 21, 2009

I would like to second this. I must have spent a large number of hours changing hard-coded URLS from test to live servers before I realised that you could do this!

5. Mel - April 23, 2009

i’m trying to use SpringWS, i follow the tutorial in the official website, but i didn’t understand many things:
first in my endPoint:
humanResourceService.bookHoliday(startDate, endDate, name);

where are “humanResourceService” and “bookHoliday” declared??? in the tutorial i did’nt read a declaration!
are they any classes missing???
i tried to deploy the sample in the documentation but i get many errors.
plz anyone could help me???

6. ttk - July 14, 2009

Download their examples and the holiday service is there.

7. Vadim - August 23, 2009

Nice, but if I have a huge types defined within my xsd file should I create all of them, or there is a posibility to generate this kind of classes? E.g. There are all information needed for HumanResourceService class creation.

8. ncrypt - September 15, 2009

Have you ever wired up spring-ws and spring mvc? Do you have an example?

9. Phill - September 15, 2009

I’m afraid I’ve never wired up Spring WS and Spring MVC together as I don’t use Spring MVC, sorry!

10. phillsacre.me.uk » Blog Archive » Packt Publishing - February 24, 2011

[…] I wanted to write a “Spring Web Services Cookbook”. Apparently this is because I once blogged on Spring Web Services. Well, let me show you the first two paragraphs of the email they sent me: Hi […]

Sorry comments are closed for this entry

%d bloggers like this: