Page History

...

This allows to throw exceptions from an application code and deal with the proper mappping mapping to an HTTP response in a registered provider.

...

In this case a template variable id available from a root class annotation is mapped to a parameter of type Long, while a name variable is mapped to a parameter of type String. Paramaters

QueryParam, HttpHeader, MatrixParam and CookieParam annotations are also supported.
Parameters can be of type String or of any type that have constructors accepting a String argument parameter or static valueOf(String s) methods. JAX-RS PathSegment is also supported.

QueryParam, HttpHeader and CookieParam annotations are also supported.

Context annotations

If a parameter or field of either UriInfo or HttpHeaders or SecurityContext or one of the Servlet types like ServeltContext or MessageBodyWorkers is annotated with a Context annotation then CXF will provide properly initialized instances to the application code.

Note that if fields are annotated with Context then care should be taken for singleton resource classes as CXF does not support yet a thread-local injection of Context fields.

Injection of contexts into message body providers is not supported yet.

Example :

A sequence of identically named parameters (queries, headers, etc) can be mapped to List or Set or SortedSet.

All the parameters are automatically decoded. This can be disabled by using @Encoded annotation.

Parameters can have a default value set using a DefaultValue annotation :

    public Response updateCustomer(@DefaultValue("123") @QueryParam("id") Long id, @PathParam("name") String name

@Path("/customer")
public class CustomerService {
    
    @Context ServletContext sc;
    @Context SecurityContext sc;
    
    @PUT
    public Response updateCustomer(@Context UriInfo u, @Context HttpHeader h, Customer c) {
        ...
    }
}

Currently this annotation is only noticed if it targets a parameter, and at the moment it can not be applied to @PathParam

There's also a CXF extension which makes it possible to inject a sequence of Path or Query parameters into a bean. For ex :

@Path("/customer/{id}")
public class CustomerService {

    
    @PUT
    @Path("{name}")
    public Response updateCustomer(@PathParam("") Customer customer) {
        ...
    }
}

public class Customer {
   public void setId(Long id) {...}
   public void setName(String s) {...}  
}

Note that there's a single @PathParam with an empty value - this is an extension bit. The value for a template variable 'id' is
injected into Customer.setId(Long id), while the value for 'name' is injected into Customer.setName(String s). The setter methods should have a single parameter, the conversion from the actual value to the parameter instance follows the same procedure as outlined above.

Starting from JAX-RS 0.8, it's also possible to inject all types of parameters into fields or through dedicated setters. For ex, the frist code fragment in this section can be rewritten like this :

@Path("/customer/{id}")
public class CustomerService {

    @PathParam("id")
    private Long id; 
    
    private String name;

    @PathParam("name")
    public setName(String name) {
        this.name = name;
    } 

    @PUT
    @Path("{name}")
    public Response updateCustomer() {
        // use id and name
    }
}

Context annotations

A number of context types can be injected as parameters, in fields or through dedicated methods.
UriInfo, SecurityContext, HttpHeaders, MessageBodyWorkers, ContextResolver, Servlet types such as HttpServletRequest
can be injected.

Example :

@Path("/customer")
public class CustomerService {
    
    @Context 
    private ServletContext sc;
    private UriInfo ui;
    
    @Context
    public void setUriInfo(UriInfo ui) {
        this.ui = ui;
    }

    @PUT
    public Response updateCustomer(@Context HttpHeaders h, Customer c) {
        ...
    }
}

Note that all types of supported JAX-RS providers such as MessageBodyWriter, MessageBodyReader, ExceptionMapper and ContextResolver, as well as the list of body providers which can be provided by MessageBodyWorkers can have contexts injected too. The only exception is that no parameter level injection is supported due to provider's methods being fixed.

Note that MessageBodyWorkers and ContextResolver are likely to be of interest to message body providers rather than to the actual application code.

You can also inject Servlet types into @Resource annotated fields. Other types would likely be supported too.

Annotation inheritance

Most of the JAX-RS annotations can be inherited from either an interface or a superclass. JAX-RS specification requires that only the ones applied to methods can be inherited. For example :

...