Package org.apache.cxf.jaxrs.cors

CORS

See:
Description

Class Summary

CorsHeaderConstants	Headers used to implement http://www.w3.org/TR/cors/.
CrossOriginResourceSharingFilter	An single class that provides both an input and an output filter for CORS, following http://www.w3.org/TR/cors/.

Annotation Types Summary

CrossOriginResourceSharing

Attach CORS information to a resource.

Package org.apache.cxf.jaxrs.cors Description

CORS

This package provides a filter to assist applications in implementing Cross Origin Resource Sharing, as described in the CORS specification.

CORS Access Model

CORS exists to protect web servers from unexpected cross-origin access. The premise of CORS is that many web resources are deployed by people who don't want to permit cross-origin access, but who couldn't detect it or didn't bother to control it. Thus, CORS defines a set of restrictions implemented on the client that, by default, prohibit cross-origin access.

If you want your service to permit cross-origin access, your service must return additional headers to the client to reassure it that you really want to permit the access. CrossOriginResourceSharingFilter adds these headers to your service's responses based on rules that you configure.

CORS Resource Model (versus JAX-RS)

CORS and JAX-RS differ, fundamentally, in how they define a resource for access control purposes. In CORS, a resource is defined by the combination of URI and HTTP method. Once a client has obtained access information for a URI+METHOD, it may cache it. JAX-RS, on the other hand, defines a resource as:

• URI
• HTTP Method
• Content-Type and Accept HTTP headers

The logical place, in other words, to specify CORS policy in a JAX-RS application is at the level of an annotated method. However, each method is applied to the narrow 'resource' defined by the list above, not just the URI+Method pair. This will motivate the annotation model below.

Simple and Preflight requests

The CORS specification differentiates two kinds of HTTP requests: simple and not simple. (See the specification for the definition.) For a simple request, the client simply sends the request to the service, and then looks for the Access-Control- headers to indicate whether the server has explicitly granted cross-origin access. For a non-simple request, the client sends a so-called preflight request and waits for a response before issuing the original request.

Configuration via Annotation

One way to control the behavior of the filter is the @CrossOriginResourceSharing annotation on a method. This is a complete solution for simple requests. You can specify all of the controls. However, if you have non-simple methods, the mismatch on resource access models above makes it impossible for CXF to map the OPTIONS request that will arrive to the correct method.

If all the methods of a class can share a common policy, you can attach a single @CrossOriginResourceSharing to a resource class, and it will apply to all the resource implied by all of the methods.

Bean Configuration

The simplest configuration applies when you want to apply the same configuration to all of your resources. In this case, you can use the properties of CrossOriginResourceSharingFilter to specify the policy.