Developing a simple SOAP-webservice using Spring 3.0.1 and Apache CXF 2.2.6

In the past few years many techniques have been developed to help applications interact with each other. One of them are webservice-interfaces. These interfaces are extremly popular in the world of Java software development. One Framework that can be used to build such interfaces is Apache CXF. Apache CXF delivers a toolset to develop interfaces using different protocols like XML/HTTP, RESTful HTTP, Corba and SOAP. In this article i’d like to show how easy it could be to develop a simple SOAP-webservice based on Apache CXF 2.2.6 and the Spring Framework 3.0.1. You can download the full example at the bottom of this article.

Setting up the project…

First I set up a small Maven 2 project that packages my application as a web application archive (*.war-file). Therefore I created the following pom.xml:

    4.0.0
    com.unitedcoders.demo
    CXFExampleService
    war
    0.0.1-SNAPSHOT
    Example Apache CXF Webservice
    http://unitedcoderscom.appspot.com

    <!-- Dependency properties -->4.5

2.2.63.0.1.RELEASE

1.1.1

    
    <!-- Plugin configuration -->CXFExampleServiceorg.apache.maven.pluginsmaven-compiler-plugin

                    1.6
                    1.6

org.apache.cxfcxf-java2ws-plugin${cxf.version}org.apache.cxfcxf-rt-frontend-jaxws${cxf.version}org.apache.cxfcxf-rt-frontend-simple${cxf.version}process-classesprocess-classes

com.unitedcoders.demo.PersonService
                            true
                            true

                            java2ws

                

    <!-- Dependency definitions -->

        <!-- Apache CXF dependencies -->

            org.apache.cxf
            cxf-rt-frontend-jaxws
            ${cxf.version}

            org.apache.cxf
            cxf-rt-transports-http
            ${cxf.version}

        <!-- Spring Dependencies -->

            org.springframework
            spring-core
            ${spring-version}

            org.springframework
            spring-web
            ${spring-version}

        <!-- Logging -->

            commons-logging
            commons-logging
            ${commons-logging-version}

        <!-- Testing -->

            junit
            junit
            ${junit-version}
            test

My projects structure

phil@invader:~/Projects/CXFExample$ tree
.
|-- README.txt
|-- pom.xml
`-- src
    |-- main
    |   |-- java
    |   |   `-- com
    |   |       `-- unitedcoders
    |   |           `-- demo
    |   |               |-- Person.java
    |   |               |-- PersonService.java
    |   |               `-- PersonServiceImpl.java
    |   |-- resources
    |   |   `-- application-context.xml
    |   `-- webapp
    |       `-- WEB-INF
    |           `-- web.xml
    `-- test
        `-- java
            `-- com
                `-- unitedcoders
                    `-- demo
                        |-- PersonServiceImplTest.java
                        `-- PersonTest.java

14 directories, 9 files
phil@invader:~/Projects/CXFExample$

Let’s first take a look on what has happened here. I defined some Apache CXF 2.2.6 dependencies which are needed to create my SOAP-webservice. To use the Spring framework in my little project I also added spring-core and spring-web in version 3.0.1 to my dependencies. Additionally I defined some other dependencies like JUnit and Apache commons-logging. But what has happend to the Maven 2 plugins? The first plugin I configured in my project is the maven-compiler-plugin. This plugin is a plugin of Mavens standard lifecycle. My configuration lets Maven 2 know which Java version should be used to compile my source. I prefer to use Java 1.6. The second plugin I defined is the cxf-java2ws-plugin. This Maven 2 plugin helps me to generate a WSDL-file from my annotated Java webservice-class.

Developing the SOAP webservice

To have a little showcase I created a simple class “Person” containing the only one member field “name”. Later on the webservice should get a persons name from a client and answer with a short greeting like „Hello [NAME]!“.

package com.unitedcoders.demo;

public class Person {

    private String name;

    public Person(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

}

After that I created a simple endpoint-interface for my webservice and annotated it as a @WebService.

package com.unitedcoders.demo;

import javax.jws.WebService;

@WebService
public interface PersonService {

    public String greetPerson(String name);

}

The implementation is as simple as the interface and is also annotated as a @WebService. Additionally the “endpointInterface” is defined as an annotation-parameter.

package com.unitedcoders.demo;

import javax.jws.WebService;

@WebService(endpointInterface = "com.unitedcoders.demo.PersonService")
public class PersonServiceImpl implements PersonService {

    public String greetPerson(String name) {
        Person person = new Person(name);

        return "Hello " + person.getName() + "!";
    }

}

That’s all. These three little files are representing my whole webservice.

Combining everything

To get the webservice working I finally combined Spring and my webservice-implementation. Therefore I first defined the applications context. First I added three imports to my applications context. There are three imports that add CXF-specific bean definitions and configurations to my applications context. After that a singleton bean of my webservice is needed. And at least a jaxws:endpoint is defined that maps my bean to the endpoint to the path “/personService”.
application-context.xml:

<!--?xml version="1.0" encoding="UTF-8"?-->

    <!-- Spring manage ServiceBean -->

    <!-- JAX-WS Service Endpoint -->

Now the context is ready to use. But what about the web.xml. The web.xml should now define a ContextLoaderListener to start up my Spring application context. Additionally a CXFServlet must be defined to make the application accessible as a webservice. I mapped to the CXFServlet to “/*”. “/*” means that all services delivered by the CXFServlet are accessible right after the context (e.g. http://[HOST]:[PORT]/[CONTEXT]/[CXFSERVLET]).

<!--?xml version="1.0" encoding="UTF-8"?-->CXF Example Webserviceorg.springframework.web.context.ContextLoaderListener

        contextConfigLocation
        classpath:application-context.xml

        CXFServlet
        org.apache.cxf.transport.servlet.CXFServlet
        1

        CXFServlet
        /*

Testing the new SOAP-webservice

After building this Maven 2 project with „mvn clean package“ a new war-file will be placed in the target folder. This war-file now contains an entire webservice. If it is deployed on a Java web container like Apache Tomcat you can reach the webservice by accessing it in your browser.

http://[YOUR TOMCAT]:[PORT]/CXFExampleService/personService?wsdl

To run some functional tests on the new webservice an test if the webservice works as expected I used soapUI which can be downloaded here. soapUI is a really famous tool that can be used to test webservices. It can be used as a standalone application or as a IDE plugin (e.g. for eclipse).

Download the full example:

DOWNLOAD

Some resources:

http://cxf.apache.org
http://www.springsource.org/download
http://www.soapui.org