What it is
Apache CXF is a framework for building robust web services in Java. It supports both RESTful (JAX-RS) and SOAP-based (JAX-WS) services, providing tools for service creation, client generation, and integration with various transports and data bindings.
CXF allows developers to create REST or SOAP services using annotations, XML configuration, or Spring integration. It supports automatic WSDL generation for SOAP, JSON/XML marshalling for REST, exception handling, interceptors, and client APIs for consuming services.
Installation
Add dependencies in pom.xml:
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-frontend-jaxrs</artifactId>
<version>3.6.1</version>
</dependency>
<dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-transports-http</artifactId>
<version>3.6.1</version>
</dependency>Getting started
The smallest useful thing you can do with it, and what each part means.
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
@Path("/hello")
public class HelloService {
@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
return "Hello Apache CXF!";
}
}import jakarta.jws.WebService;
@WebService(endpointInterface = "com.example.HelloService")
public class HelloServiceImpl implements HelloService {
public String sayHello(String name) {
return "Hello, " + name;
}
}Advanced usage
Where the library earns its place over a simpler alternative.
import org.apache.cxf.jaxrs.JAXRSServerFactoryBean;
JAXRSServerFactoryBean factory = new JAXRSServerFactoryBean();
factory.setResourceClasses(HelloService.class);
factory.setAddress("http://localhost:8080/");
factory.create();import org.apache.cxf.jaxws.JaxWsProxyFactoryBean;
JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean();
factory.setServiceClass(HelloService.class);
factory.setAddress("http://localhost:8080/HelloService");
HelloService client = (HelloService) factory.create();
String response = client.sayHello("Alice");import org.apache.cxf.interceptor.LoggingInInterceptor;
import org.apache.cxf.interceptor.LoggingOutInterceptor;
factory.getInInterceptors().add(new LoggingInInterceptor());
factory.getOutInterceptors().add(new LoggingOutInterceptor());import jakarta.ws.rs.ext.ExceptionMapper;
import jakarta.ws.rs.ext.Provider;
import jakarta.ws.rs.core.Response;
@Provider
public class GenericExceptionMapper implements ExceptionMapper<Exception> {
public Response toResponse(Exception e) {
return Response.status(500).entity(e.getMessage()).build();
}
}Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- WebApplicationException
- Use for returning specific HTTP status codes in REST endpoints.
- SOAPFaultException
- Thrown when a SOAP request fails. Inspect fault code and message for debugging.
- EndpointException
- Occurs when the service endpoint fails to start or bind. Verify port availability and configuration.
Best practices
- Use annotations (@Path, @GET, @POST, @WebService) for clarity and standardization.
- Leverage CXF interceptors for cross-cutting concerns like logging, metrics, and security.
- Separate service interfaces and implementations for maintainability.
- Use Spring or CDI integration for dependency injection.
- Document REST endpoints using OpenAPI and SOAP services using WSDL.
Background
Why it exists, and what it was reacting to.
Apache CXF was developed to simplify building and deploying web services in Java. It offers a flexible architecture supporting multiple protocols (HTTP, JMS, TCP), pluggable data bindings (JAXB, JSON, XML), and integration with Spring and CDI. CXF is widely used in enterprise applications that require interoperability, SOAP-based services, or hybrid REST/SOAP architectures.