Apache CXF — Complete Web Services Reference Guide

Learning Path

    flowchart LR
    A["Cxf Overview"] --> B["Core Concepts"]
    B --> C["Intermediate Topics"]
    C --> D["Advanced Topics"]
    D --> E["Practical Applications"]
    A --> F["You Are Here"]
    style F fill:#f90,color:#fff
  

Apache CXF is an open-source services framework that helps build and develop services using JAX-WS (SOAP) and JAX-RS (REST) APIs — enabling Java developers to create enterprise-grade web services.

What You’ll Learn

By the end of this tutorial, you’ll create SOAP web services with JAX-WS annotations, build RESTful APIs with JAX-RS, configure interceptors for message processing, integrate CXF with Spring Boot, and understand when to use SOAP vs REST.

Why Apache CXF Matters

Enterprise integration often requires both SOAP (for legacy systems, WS-Security) and REST (for modern APIs). CXF provides both in one framework. It’s used by banks, healthcare systems, and government agencies where reliability and standards compliance are critical. DodaTech’s enterprise products use CXF for secure SOAP-based integrations with legacy backend systems.

JAX-WS (SOAP)

SOAP (Simple Object Access Protocol) is an XML-based protocol for structured information exchange:

import javax.jws.WebService;
import javax.jws.WebMethod;

// Service interface
@WebService
public interface ProductService {
    @WebMethod
    Product getProduct(int id);

    @WebMethod
    List<Product> getAllProducts();
}

// Service implementation
@WebService(endpointInterface = "com.example.ProductService")
public class ProductServiceImpl implements ProductService {
    public Product getProduct(int id) {
        return productRepository.findById(id);
    }

    public List<Product> getAllProducts() {
        return productRepository.findAll();
    }
}

Line-by-line explanation:

• @WebService — declares this interface as a SOAP web service. CXF generates a WSDL (Web Services Description Language) document automatically.
• @WebMethod — marks a method as exposed through SOAP. Without this annotation, the method is not part of the web service contract.
• @WebService(endpointInterface = "...") — links the implementation to the service interface. CXF uses the interface to generate the WSDL.

How SOAP works: The server publishes a WSDL (an XML contract describing the service). The client reads the WSDL, generates Java classes from it, and makes SOAP calls. Think of WSDL like a menu — it tells clients what dishes (methods) are available and what ingredients (parameters) they need.

JAX-RS (REST)

RESTful services use HTTP methods and JSON/XML:

import javax.ws.rs.*;
import javax.ws.rs.core.*;

@Path("/products")
@Produces(MediaType.APPLICATION_JSON)
public class ProductResource {

    @GET
    public List<Product> getAll() {
        return productService.findAll();
    }

    @GET
    @Path("/{id}")
    public Product getById(@PathParam("id") int id) {
        return productService.findById(id);
    }

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    public Response create(Product product) {
        Product created = productService.create(product);
        return Response.status(201).entity(created).build();
    }

    @PUT
    @Path("/{id}")
    public Product update(@PathParam("id") int id, Product product) {
        return productService.update(id, product);
    }

    @DELETE
    @Path("/{id}")
    public Response delete(@PathParam("id") int id) {
        productService.delete(id);
        return Response.noContent().build();
    }
}

Line-by-line:

• @Path("/products") — maps all methods in this class to /api/products (base path)
• @GET / @POST / @PUT / @DELETE — HTTP method mapping. GET retrieves, POST creates, PUT updates, DELETE removes.
• @Produces(MediaType.APPLICATION_JSON) — the response format. CXF automatically serializes Java objects to JSON.
• @Consumes(MediaType.APPLICATION_JSON) — the request body format. CXF automatically deserializes JSON to Java objects.
• @PathParam("id") — extracts the {id} value from the URL path

Spring Boot Integration

@SpringBootApplication
@ImportResource("classpath:cxf-config.xml")
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Interceptors

Interceptors process messages before or after the service method:

public class LoggingInterceptor extends AbstractPhaseInterceptor<Message> {
    public LoggingInterceptor() {
        super(Phase.RECEIVE);  // runs when message is received
    }

    public void handleMessage(Message message) {
        // Log the incoming message
        System.out.println("Received: " + message);
    }
}

SOAP vs REST — When to Use Which

Common Mistakes

1. Forgetting @WebMethod on service interface methods

Without @WebMethod, the method is not exposed in the WSDL. The client won’t see it.

2. Not handling both JSON and XML in JAX-RS

By default, JAX-RS may only support XML. Add the proper providers (Jackson for JSON) to ensure both formats work.

3. Ignoring WS-Security for production SOAP

SOAP without security sends credentials in plain text. Configure WS-Security policies for production deployment.

4. Using SOAP when REST would suffice

SOAP adds complexity (XML envelopes, WSDL management) that most modern applications don’t need. Default to REST unless you need WS-Security or transactional guarantees.

5. Not configuring proper exception mappers

Unhandled exceptions return generic 500 errors with stack traces. Implement ExceptionMapper to return proper error responses.

Practice Questions

1. What annotations are needed for a JAX-WS SOAP service?

Answer: @WebService on the interface, @WebMethod on methods, @WebService(endpointInterface=...) on the implementation class.

2. How do you extract a path parameter in JAX-RS?

Answer: Use @PathParam("id") on the method parameter, with @Path("/{id}") on the method.

3. What is the difference between @Produces and @Consumes?

Answer: @Produces sets the response media type (what the server sends). @Consumes sets the request media type (what the server accepts).

4. When should you choose SOAP over REST?

Answer: When you need WS-Security, transactional guarantees, or must integrate with legacy enterprise systems that require strict contract-first development.

Challenge

Build a RESTful book catalog API with CXF + Spring Boot: endpoints for CRUD operations, JSON serialization, proper HTTP status codes, error handling, and Swagger documentation.

FAQ

Try It Yourself

// 1. Create a Spring Boot project with CXF dependencies
// Maven:
// <dependency>
//   <groupId>org.apache.cxf</groupId>
//   <artifactId>cxf-spring-boot-starter-jaxrs</artifactId>
//   <version>4.0.x</version>
// </dependency>

// 2. Create a simple REST resource
@Path("/hello")
public class HelloResource {
    @GET
    @Produces("text/plain")
    public String sayHello() {
        return "Hello from CXF!";
    }
}

// 3. Configure CXF in application.properties
// cxf.path=/api

// 4. Start the app and test
// curl http://localhost:8080/api/hello

What’s Next

Explore more Java enterprise frameworks:

Related topics to explore:

• Java Enterprise
• Spring Boot
• API Deployment