Playing with Spring WS

I played around with the Spring WebService library and this is a summary of what I did or what you need to take care of while implementing your own web service.

My toy project Whois-WS is about domain WHOIS information. You can ask the service about a domain name and it will return basic information about the domain, such as the domain name, connection status and responsible whois server.
To begin with, use the tutorial to start. You'll learn pretty fast with it. Really great tutorial and covers all the stuff to get warm with the topic.

1.) Take time to think about what your service does before you start developing your own service. Take care to not make your Business Object Model (BOM) too complex.

My example is going to be a password-secured WHOIS Service, which provides information about a domain name.

2.) Start with a simple "Hello World" example, use simple String input and String output. When you've got that running, go on and make your BOM with more complex types.



3.) Immediately document your BOM with XML Schema Annotations. Give examples for your values. That will be visible in the dynamically generated WSDL.



4.) The .wsdl file is always reachable at "/yourwebapp/foo.wsdl", with foo being the Bean ID of your WsdlDefinition.



5.) Use JAXB2 + Maven + Spring-WS. Besides spring-ws artifacts and junit, you'll need the following dependencies:

	com.sun.xml.messaging.saaj
	saaj-impl
	1.3
	runtime


	javax.xml.bind
	jaxb-api
	2.0


	com.sun.xml.bind
	jaxb-impl
	2.0.3

6.) Be aware to use your BOM in your business service! Don't map stuff around. DRY! JAXB2 Generated beans are clean enough to use them as Domain Object Model. My MarshallingEndpoint remains pretty simple:

@Override
protected Object invokeInternal(Object requestObject) throws Exception {
	log.debug("invokeInternal");
	WhoisRequest request = (WhoisRequest) requestObject;
	WhoisResponse response = service.whois(request);
	response.setResponseTimestamp(DatatypeFactory.newInstance()
			.newXMLGregorianCalendar(new GregorianCalendar()));
	return response;
}

7.) Use soapui to test your requests. Makes it pretty easy to test how it works, even with WS-Security enabled. (Password Digest for starters). Also, try to use a timestamp in your response, which is set by your technical layer. That way, you can quickly verify you get new responses.



8.) Don't separate a static WSDL and your XSD. Spring does not like that, and Maven neither. You'll end up with copying your xsd files anywhere in your project paths to have them in a) the Eclipse WSDL Editor b) the Eclipse XML Schema Editor c) the WEB-INF folder for the WebApp d) the test/resources source folder for unit tests e) in the webapp root for your browser/soap client to access the XSD. Use only one XSD, and import common types from another one.



9.) Use transformWsdlLocations servlet parameter to get rid of the hardcoded localhost:8080 SOAP address location

  spring-ws
  org.spring...MessageDispatcherServlet
  
  
      transformWsdlLocations
      true
  

10) When you use SoapActionEndpointMapping and as client WebServiceTemplate, be sure to add the SOAPAaction request property to the client call, otherwise you will end up with "404 Not Found" errors.

// WebService Client call
WebServiceTemplate webServiceTemplate = new WebServiceTemplate();
webServiceTemplate.setDefaultUri("http://127.0.0.1:8080/whois-ws/");
HttpUrlConnectionMessageSender messageSender =
	new HttpUrlConnectionMessageSender() {
	@Override
	public WebServiceConnection
		createConnection(String uri)
			throws IOException {
		HttpUrlConnection createConnection =
		 (HttpUrlConnection) super.createConnection(uri);
		createConnection.getConnection().
		setRequestProperty("SOAPAction","http://.../whois/Whois");
		return createConnection;
	}
};
webServiceTemplate.setMessageSender(messageSender);
webServiceTemplate.sendSourceAndReceiveToResult(
	new StringSource(wsRequest.toString()), result);

I finished the project setup and did a 1.0.0 release and deployed it to my server, so you can test it with a live demo.

The project web site is available here:
http://www.smartwerkz.com/projects/whois-ws/

If you want to try it out, you can find the WSDL here:
http://www.smartwerkz.com/whois-ws/whois.wsdl

Or if you do not want to use your own WS Client or SOAP testing tool, you can use a simple HTML GUI:
http://www.smartwerkz.com/whois-ws/whois.html

Download the source package here:
whois-ws-20080709-src.zip

Happy serving!

• Comments (4)
• Trackback (1)