In my endless search for the best way to develop applications, I’ve recently been interested in web services in general and contract-first in particular. Web services are coined contract-first when the WSDL is designed in the first place and classes are generated from it. They are acknowledged to be the most interoperable of web services, since the WSDL is agnostic from the underlying technology.

In the past, I’ve been using Axis2 and then CXF but now, JavaEE provides us with the power of JAX-WS (which is aimed at SOAP, JAX-RS being aimed at REST). There’s also a Spring Web Services sub-project.

My first goal was to check how easy it was to inject through Spring in both technologies but during the course of my development, I came across other comparison areas.

Overview

With Spring Web Services, publishing a new service is a 3-step process:

1. Add the Spring MessageDispatcherServlet in the web deployment descriptor.

   <web-app version="2.5" ...>
       <context-param>
           <param-name>contextConfigLocation</param-name>
           <param-value>classpath:/applicationContext.xml</param-value>
       </context-param>
       <servlet>
           <servlet-name>spring-ws</servlet-name>
           <servlet-class>org.springframework.ws.transport.http.MessageDispatcherServlet</servlet-class>
           <init-param>
               <param-name>transformWsdlLocations</param-name>
               <param-value>true</param-value>
           </init-param>
           <init-param>
               <param-name>contextConfigLocation</param-name>
               <param-value>classpath:/spring-ws-servlet.xml</param-value>
           </init-param>
       </servlet>
       <servlet-mapping>
           <servlet-name>spring-ws</servlet-name>
           <url-pattern>/spring/*</url-pattern>
       </servlet-mapping>
       <listener>
           <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
       </listener>
   </web-app>

2. Create the web service class and annotate it with @Endpoint. Annotate the relevant service methods with @PayloadRoot. Bind the method parameters with @RequestPayload and the return type with @ResponsePayload.

   @Endpoint
   public class FindPersonServiceEndpoint {
   
       private final PersonService personService;
   
       public FindPersonServiceEndpoint(PersonService personService) {
   
           this.personService = personService;
       }
   
       @PayloadRoot(localPart = "findPersonRequestType", namespace = "http://blog.frankel.ch/ws-inject")
       @ResponsePayload
       public FindPersonResponseType findPerson(@RequestPayload FindPersonRequestType parameters) {
   
           return new FindPersonDelegate().findPerson(personService, parameters);
       }
   }

3. Configure the web service class as a Spring bean in the relevant Spring beans definition file.

   <beans ...>
       <sws:annotation-driven />
       <bean class="ch.frankel.blog.wsinject.impl.FindPersonServiceEndpoint">
           <constructor-arg>
               <ref bean="personService" />
           </constructor-arg>
       </bean>
   </beans>

   For JAX-WS (Metro implementation), the process is very similar:
4. Add the WSServlet in the web deployment descriptor:

   <web-app version="2.5" ...>
       <servlet>
           <servlet-name>jaxws-servlet</servlet-name>
           <servlet-class>com.sun.xml.ws.transport.http.servlet.WSServlet</servlet-class>
       </servlet>
       <servlet-mapping>
           <servlet-name>jaxws-servlet</servlet-name>
           <url-pattern>/jax/*</url-pattern>
       </servlet-mapping>
       <listener>
           <listener-class>com.sun.xml.ws.transport.http.servlet.WSServletContextListener</listener-class>
       </listener>
   </web-app>

5. Create the web service class:

   @WebService(endpointInterface = "ch.frankel.blog.wsinject.jaxws.FindPersonPortType")
   public class FindPersonSoapImpl extends SpringBeanAutowiringSupport implements FindPersonPortType {
   
       @Autowired
       private PersonService personService;
   
       @Override
       public FindPersonResponseType findPerson(FindPersonRequestType parameters) {
   
           return new FindPersonDelegate().findPerson(personService, parameters);
       }
   }

6. Finally, we also have to configure the service, this time in the standard Metro configuration file (sun-jaxws.xml):

   <endpoints version="2.0" ...>
       <endpoint name="FindPerson"
           implementation="ch.frankel.blog.wsinject.impl.FindPersonSoapImpl"
           url-pattern="/jax/findPerson" />
   </endpoints>

Creating a web service in Spring or JAX-WS requires the same number of steps of equal complexity.

Code generation

In both cases, we need to generate Java classes from the Web Service Definitions File (WSDL). This is completely independent from the chosen technology.
However, whereas JAX-WS uses all generated Java classes, Spring WS uses only the ones that maps to WSD types and elements: wiring the WS call to the correct endpoint is achieved by mapping the request and response types.

The web service itself

Creating the web service in JAX-RS is just a matter of implementing the port type interface, which contains the service method.
In Spring, the service class has to be annotated with @Endpoint to be rcognized as a service class.

URL configuration

In JAX-RS, the sun-jaxws.xml file syntax let us configure very finely how each URL is mapped to a particular web service.
In Spring WS, no such configuration is available.
Since I’d rather have an overview of the different URLs, my preferences go toward JAX-WS.

Spring dependency injection

Injecting a bean in a Spring WS is very easy since the service is already a Spring bean thanks to the <sws:annotation-driven /> part.
On the contrary, injecting a Spring bean requires our JAX-WS implementation to inherit from SpringBeanAutowiringSupport which prevent us from having our own hierarchy. Also, we are forbidden from using explicit XML wiring then.
It’s easier to get dependency injection with Spring WS (but that was expected).

Exposing the WSDL

Both JAX-WS and Spring WS are able to expose a WSDL. In order to do so, JAX-WS uses the generated classes and as such, the exposed WSDL is the same as the one we designed in the first place.
On the contrary, Spring provides us with 2 options:

• either use the static WSDL in which it replaces the domain and port in the <soap:address> section
• or generate a dynamic WSDL from XSD files, in which case the designed one and the generated one aren’t the same

Integration testing

Spring WS has one feature that JAX-WS lacks: integration testing. A test class that will be configured with Spring Beans definitions file(s) can be created to assert sent output messages agains known inputs. Here’s an example of such a test, based on both Spring test and TestNG:

@ContextConfiguration(locations = { "classpath:/spring-ws-servlet.xml", "classpath:/applicationContext.xml" })
public class FindPersonServiceEndpointIT extends AbstractTestNGSpringContextTests {

    @Autowired
    private ApplicationContext applicationContext;

    private MockWebServiceClient client;

    @BeforeMethod
    protected void setUp() {

        client = MockWebServiceClient.createClient(applicationContext);
    }

    @Test
    public void findRequestPayloadShouldBeSameAsExpected(String request, String expectedResponse) throws DatatypeConfigurationException {

        int id = 5;

        Source requestPayload = new StringSource(request);

        Source expectedResponsePayload = new StringSource(expectedResponse);

        String request = "<a:findPersonRequestType xmlns:a='http://blog.frankel.ch/ws-inject'><id>"
            + id + "</id></a:findPersonRequestType>";

        GregorianCalendar calendar = new GregorianCalendar();

        XMLGregorianCalendar xmlCalendar = DatatypeFactory.newInstance().newXMLGregorianCalendar(calendar);

        xmlCalendar.setHour(FIELD_UNDEFINED);
        xmlCalendar.setMinute(FIELD_UNDEFINED);
        xmlCalendar.setSecond(FIELD_UNDEFINED);
        xmlCalendar.setMillisecond(FIELD_UNDEFINED);

        String expectedResponse = "<ns3:findPersonResponseTypexmlns:ns3='http://blog.frankel.ch/ws-inject'><person><id>"
            + id
            + "</id><firstName>John</firstName><lastName>Doe</lastName><birthdate>"
            + xmlCalendar.toXMLFormat()
            + "</birthdate></person></ns3:findPersonResponseType>";

        client.sendRequest(withPayload(requestPayload)).andExpect(payload(expectedResponsePayload));
    }
}

Note that I encountered problems regarding XML suffixes since not only is the namespace checked, but also the prefix name itself (which is a terrible idea).

Included and imported schema resolution

On one side, JAX-WS inherently resolves included/imported schemas without a glitch.
On the other side, we need to add specific beans in the Spring context in order to be able to do it with Spring WS:

<!-- Let us reference XML schemas -->
<bean class="org.springframework.ws.transport.http.XsdSchemaHandlerAdapter" />
<!-- Let us resolve person.xsd reference in the WSDL -->
<bean id="person" class="org.springframework.xml.xsd.SimpleXsdSchema">
    <property name="xsd" value="classpath:/wsdl/person.xsd" />
</bean>

Miscellaneous

JAX-WS provides an overview of all published services at the root of the JAX-WS servlet mapping:

Conclusion

Considering contract-first web services, my little experience has driven me to choose JAX-WS in favor of Spring WS: testing benefits do not balance the ease-of-use of the standard. I must admit I was a little surprised by these results since most Spring components are easier to use and configure than their standard counterparts, but results are here.

You can find the sources for this article here.

Note: the JAX-WS version used is 2.2 so the Maven POM is rather convoluted to override Java 6 native JAX-WS 2.1 classes.