CXF supports JAX-RS (JSR-311), Java API for RESTful Web Services. JAX-RS provides a more standard way to build RESTful services in Java. CXF 2.2-SNAPSHOT supports the final version of JSR-311 API while CXF 2.1.x currently supports only the 0.8 version of JSR-311 API .

...

• @ProduceMime and @ConsumeMime have been replaced with @Produces and @Consumes respectively
• HttpHeaders has had some of its methods returning a string representation of Locale updated to return Locale instead

Note that all the fixes applied to the JAX-RS implementation in the trunk will be available for users of 0.8 api, with the exception of 1.0 api specific fixes.

As JAX-RS API 1.0 is currently supported in CXF 2.2-SNAPSHOT, it's also worth noting of the following changes in dependencies :

...

Please check the pom.xml for the list of cxf components used by the JAX-RS implementation.

CXF JAX-RS bundle

A standalone JAX-RS bundle is now available which may be of interest to users doing JAX-RS work only. Some updates to the pom is needed to ensure some of the artifacts pulled in as part of a dependency on cxf-api are actually omitted - contributions are welcome.

Understanding the basics

...

package demo.jaxrs.server;

import java.util.HashMap;
import java.util.Map;

import javax.ws.rs.GET;
import javax.ws.rs.ProducesPath;
import javax.ws.rs.PathPathParam;
import javax.ws.rs.PathParamProduces;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriInfo;

@Path("/customerservice/")
@ProduceMime@Produces("application/xml")
public class CustomerService {

    public CustomerService() {
    }

    @GET
    public Customers getCustomers() {
        ......
    }

    @GET
    @Path("/customers/{id}")
    @Produces("application/json")
    public Customer getCustomer(@PathParam("id") String id) {
        ......
    }

    @PUT
    @Path("/customers/{id}")
    @Consumes("application/xml")
    public Response updateCustomer(@PathParam("id") Long id, Customer customer) {
        ......
    }

    @POST
    @Path("/customers")
    public Response addCustomer(Customer customer) {
        ......
    }

    @DELETE
    @Path("/customers/{id}/")
    public Response deleteCustomer(@PathParam("id") String id) {
        ......
    }

    @Path("/orders/{orderId}/")
    public Order getOrder(@PathParam("orderId") String orderId) {
       ......
    }
}

Customer resource class can handle requests starting from /customerservice. When /customerservice request is matched to this class, its getCustomers() method will be selected. updateCustomer(), deleteCustomer() and addCustomer() are used to serve POST, PUT and DELETE requests starting from /customerservice/customer, while getOrder() method delegates the handling of requests like /customerservice/orders/1 to a subresource locator Order.

ProduceMime @Produces annotation is used to specify the format of the response. When not available on the resource method, it's inherited from a class, and if it's not available on the class then it's inherited from a corresponding message body writer, if any. Default value is */*, but it's recommended that some definite value is specified. The same applies to ConsumeMime@Consumes, only it's message body readers that are checked as the last resort.

For example, getCustomers() method inherits the ProduceMime @Produces annotation from its class, while getCustomer() method overrides it with its own value.

...

@Path annotation is applied to resource classes or methods. The value of @Path annotation is a relative URI path and follows the URI Template format and may include arbitrary regular expressions. When not available on the resource method, it's inherited from a class. For example :

@GET
@Path("/customers/{id}")
public class CustomerResource {

    public Customer getCustomer(@PathParam("id") Long id) {
        ......
    }

    @Path("/order/{orderid}")
    public Order getOrder(@PathParam("id") Long customerId, @PathParam("orderid") Long orderId) {
        ......
    }

    @Path("/order/{orderid}/{search:.*}")
    public Item findItem(@PathParam("id") Long customerId, 
                         @PathParam("orderid") Long orderId,
                         @PathParam("search") String searchString,
                         @PathParam("search") List<PathSegment> searchList) {
        ......
    }
}

This example is similar to the one above it, but it also shows that a /@GET annotation is inherited by resource methods, an {id} template variable specified as part of the root @Path expression is reused by resource methods and a custom reqular expression is specified by a findItem() method (note that a variable name is separated by ':' from an actual expression).

In this example, a request like 'GET /customers/1/order/2/price/2000/weight/2' will be served by the findItem() method.
List<PathSegment> can be used to get to all the path segments in 'price/2000/weight/2' captured by the regular expression.

More information about Path annotations can be found from JAX-RS spec section 2.3.

...