Introduction to Apache CXF

1. Overview

Apache CXF is a JAX-WS fully compliant framework.

On top of features defined by JAX-WS standards, Apache CXF provides the capability of conversion between WSDL and Java classes, APIs used to manipulate raw XML messages, the support for JAX-RS, integration with the Spring Framework, etc.

This tutorial is the first of a series on Apache CXF, introducing basic characteristics of the framework. It only uses the JAX-WS standard APIs in source code while still takes advantage of Apache CXF behind the scenes, such as automatically generated WSDL metadata and CXF default configuration.

2. Maven Dependencies

The key dependency needed to use Apache CXF is org.apache.cxf:cxf–rt–frontend–jaxws. This provides a JAX-WS implementation to replace the built-in JDK one:

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-frontend-jaxws</artifactId>
    <version>3.1.6</version>
</dependency>

Notice that this artifact contains a file named javax.xml.ws.spi.Provider inside the META-INF/services directory. Java VM looks at the first line of this file to determine the JAX-WS implementation to make use of. In this case, content of the line is org.apache.cxf.jaxws.spi.ProviderImpl, referring to the implementation supplied by Apache CXF.

In this tutorial, we do not use a servlet container to publish the service, therefore another dependency is required to provide necessary Java type definitions:

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http-jetty</artifactId>
    <version>3.1.6</version>
</dependency>

For the latest versions of these dependencies, please check out cxf-rt-frontend-jaxws and cxf-rt-transports-http-jetty in the Maven central repository.

3. Web Service Endpoint

Let’s start with the implementation class used to configure the service endpoint:

@WebService(endpointInterface = "com.baeldung.cxf.introduction.Baeldung")
public class BaeldungImpl implements Baeldung {
    private Map<Integer, Student> students 
      = new LinkedHashMap<Integer, Student>();

    public String hello(String name) {
        return "Hello " + name;
    }

    public String helloStudent(Student student) {
        students.put(students.size() + 1, student);
        return "Hello " + student.getName();
    }

    public Map<Integer, Student> getStudents() {
        return students;
    }
}

The most important thing to be noticed over here is the presence of the endpointInterface attribute in the @WebService annotation. This attribute points to an interface defining an abstract contract for the web service.

All method signatures declared in the endpoint interface need to be implemented, but it’s not required to implement the interface.

Here the BaeldungImpl implementation class still implements the following endpoint interface to make it clear that all the declared methods of the interface have been implemented, but doing this is optional:

@WebService
public interface Baeldung {
    public String hello(String name);

    public String helloStudent(Student student);

    @XmlJavaTypeAdapter(StudentMapAdapter.class)
    public Map<Integer, Student> getStudents();
}

By default, Apache CXF uses JAXB as its data binding architecture. However, since JAXB does not directly support binding of a Map, which is returned from the getStudents method, we need an adapter to convert the Map to a Java class that JAXB can use.

In addition, in order to separate contract elements from their implementation, we define Student as an interface and JAXB does not directly support interfaces either, thus we need one more adapter to deal with this. In fact, for convenience, we may declare Student as a class. The use of this type as an interface is just one more demonstration of using adaptation classes.

The adapters are demonstrated in the section right below.

4. Custom Adapters

This section illustrates the way to use adaptation classes to support binding of a Java interface and a Map using JAXB.

4.1. Interface Adapter

This is how the Student interface is defined:

@XmlJavaTypeAdapter(StudentAdapter.class)
public interface Student {
    public String getName();
}

This interface declares only one method returning a String and specifies StudentAdapter as the adaptation class to map itself to and from a type that can apply JAXB binding.

The StudentAdapter class is defined as follows:

public class StudentAdapter extends XmlAdapter<StudentImpl, Student> {
    public StudentImpl marshal(Student student) throws Exception {
        if (student instanceof StudentImpl) {
            return (StudentImpl) student;
        }
        return new StudentImpl(student.getName());
    }

    public Student unmarshal(StudentImpl student) throws Exception {
        return student;
    }
}

An adaptation class must implement the XmlAdapter interface and provide implementation for the marshal and unmarshal methods. The marshal method transforms a bound type (Student, an interface that JAXB cannot directly handle) into a value type (StudentImpl, a concrete class that can be processed by JAXB). The unmarshal method does things the other way around.

Here is the StudentImpl class definition:

@XmlType(name = "Student")
public class StudentImpl implements Student {
    private String name;

    // constructors, getter and setter
}

4.2. Map Adapter

The getStudents method of Baeldung endpoint interface returns a Map and indicates an adaptation class to convert the Map to a type that can be handled by JAXB. Similar to the StudentAdapter class, this adaptation class must implement marshal and unmarshal methods of the XmlAdapter interface:

public class StudentMapAdapter 
  extends XmlAdapter<StudentMap, Map<Integer, Student>> {
    public StudentMap marshal(Map<Integer, Student> boundMap) throws Exception {
        StudentMap valueMap = new StudentMap();
        for (Map.Entry<Integer, Student> boundEntry : boundMap.entrySet()) {
            StudentMap.StudentEntry valueEntry  = new StudentMap.StudentEntry();
            valueEntry.setStudent(boundEntry.getValue());
            valueEntry.setId(boundEntry.getKey());
            valueMap.getEntries().add(valueEntry);
        }
        return valueMap;
    }

    public Map<Integer, Student> unmarshal(StudentMap valueMap) throws Exception {
        Map<Integer, Student> boundMap = new LinkedHashMap<Integer, Student>();
        for (StudentMap.StudentEntry studentEntry : valueMap.getEntries()) {
            boundMap.put(studentEntry.getId(), studentEntry.getStudent());
        }
        return boundMap;
    }
}

The StudentMapAdapter class maps Map<Integer, Student> to and from the StudentMap value type with the definition as follows:

@XmlType(name = "StudentMap")
public class StudentMap {
    private List<StudentEntry> entries = new ArrayList<StudentEntry>();

    @XmlElement(nillable = false, name = "entry")
    public List<StudentEntry> getEntries() {
        return entries;
    }

    @XmlType(name = "StudentEntry")
    public static class StudentEntry {
        private Integer id;
        private Student student;

        // getters and setters
    }
}

5. Deployment

5.1. Server Definition

In order to deploy the web service discussed above, we will make use of the standard JAX-WS APIs. Since we are using Apache CXF, the framework does some extra work, e.g. generating and publishing the WSDL schema. Here is how the service server is defined:

public class Server {
    public static void main(String args[]) throws InterruptedException {
        BaeldungImpl implementor = new BaeldungImpl();
        String address = "http://localhost:8080/baeldung";
        Endpoint.publish(address, implementor);
        Thread.sleep(60 * 1000);        
        System.exit(0);
    }
}

After the server is active for a while to facilitate testing, it should be shut down to release system resources. You may specify any working duration for the server based on your needs by passing a long argument to the Thread.sleep method.

5.2. Deployment of the Server

In this tutorial, we use the org.codehaus.mojo:exec-maven-plugin plugin to instantiate the server illustrated above and control its lifecycle. This is declared in the Maven POM file as follows:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <configuration>
        <mainClass>com.baeldung.cxf.introduction.Server</mainClass>
    </configuration>
</plugin>

The mainClass configuration refers to the Server class where the web service endpoint is published. After running the java goal of this plugin, we can check out the WSDL schema automatically generated by Apache CXF by accessing the URL http://localhost:8080/baeldung?wsdl.

6. Test Cases

This section walks you through steps to write test cases used to verify the web service we created before.

Please note that we need to execute the exec:java goal to start the web service server before running any test.

6.1. Preparation

The first step is to declare several fields for the test class:

public class StudentTest {
    private static QName SERVICE_NAME 
      = new QName("http://introduction.cxf.baeldung.com/", "Baeldung");
    private static QName PORT_NAME 
      = new QName("http://introduction.cxf.baeldung.com/", "BaeldungPort");

    private Service service;
    private Baeldung baeldungProxy;
    private BaeldungImpl baeldungImpl;

    // other declarations
}

The following initializer block is used to initiate the service field of the javax.xml.ws.Service type prior to running any test:

{
    service = Service.create(SERVICE_NAME);
    String endpointAddress = "http://localhost:8080/baeldung";
    service.addPort(PORT_NAME, SOAPBinding.SOAP11HTTP_BINDING, endpointAddress);
}

After adding JUnit dependency to the POM file, we can use the @Before annotation as in the code snippet below. This method runs before every test to re-instantiate Baeldung fields:

@Before
public void reinstantiateBaeldungInstances() {
    baeldungImpl = new BaeldungImpl();
    baeldungProxy = service.getPort(PORT_NAME, Baeldung.class);
}

The baeldungProxy variable is a proxy for the web service endpoint, while baeldungImpl is just a simple Java object. This object is used to compare results of invocations of remote endpoint methods through the proxy with invocations of local methods.

Note that a QName instance is identified by two parts: a Namespace URI and a local part. If the PORT_NAME argument, of the QName type, of the Service.getPort method is omitted, Apache CXF will assume that argument’s Namespace URI is the package name of the endpoint interface in the reverse order and its local part is the interface name appended by Port, which is the exact same value of PORT_NAME. Therefore, in this tutorial we may leave this argument out.

6.2. Test Implementation

The first test case we illustrate in this sub-section is to validate the response returned from a remote invocation of the hello method on the service endpoint:

@Test
public void whenUsingHelloMethod_thenCorrect() {
    String endpointResponse = baeldungProxy.hello("Baeldung");
    String localResponse = baeldungImpl.hello("Baeldung");
    assertEquals(localResponse, endpointResponse);
}

It is clear that the remote endpoint method returns the same response as the local method, meaning the web service works as expected.

The next test case demonstrates the use of helloStudent method:

@Test
public void whenUsingHelloStudentMethod_thenCorrect() {
    Student student = new StudentImpl("John Doe");
    String endpointResponse = baeldungProxy.helloStudent(student);
    String localResponse = baeldungImpl.helloStudent(student);
    assertEquals(localResponse, endpointResponse);
}

In this case, the client submits a Student object to the endpoint and receives a message containing the student’s name in return. Like the previous test case, the responses from both remote and local invocations are the same.

The last test case that we show over here is more complicated. As defined by the service endpoint implementation class, each time the client invokes the helloStudent method on the endpoint, the submitted Student object will be stored in a cache. This cache can by retrieved by calling the getStudents method on the endpoint. The following test case confirms that content of the students cache represents what the client has sent to the web service:

@Test
public void usingGetStudentsMethod_thenCorrect() {
    Student student1 = new StudentImpl("Adam");
    baeldungProxy.helloStudent(student1);

    Student student2 = new StudentImpl("Eve");
    baeldungProxy.helloStudent(student2);
        
    Map<Integer, Student> students = baeldungProxy.getStudents();       
    assertEquals("Adam", students.get(1).getName());
    assertEquals("Eve", students.get(2).getName());
}

7. Conclusion

This tutorial introduced Apache CXF, a powerful framework to work with web services in Java. It focused on the application of the framework as a standard JAX-WS implementation, while still making use of the framework’s specific capabilities at run-time.