//  ========================================================================
//  Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
//  ========================================================================
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================

[[cross-origin-filter]]
=== Cross Origin Filter

[[cross-origin-filter-metadata]]
==== Info

* Classname: `org.eclipse.jetty.servlets.CrossOriginFilter`
* Maven Artifact: org.eclipse.jetty:jetty-servlets
* Javadoc: {JDURL}/org/eclipse/jetty/servlets/CrossOriginFilter.html
* Xref: {JXURL}/org/eclipse/jetty/servlets/CrossOriginFilter.html

[[cross-origin-filter-usage]]
==== Usage

HTTP requests made from a script are subject to well known restrictions, the most prominent being the same domain policy.

Firefox 3.5 introduced support for W3C's Access Control for Cross-Site Requests specification, which requires a compliant client (for example, Firefox 3.5) and a compliant server (via this servlet filter).

This filter implements the required bits to support the server-side contract of the specification, and will allow a compliant client to perform cross-domain requests via the standard XMLHttpRequest object.
If the client does not issue a compliant cross-domain request, this filter does nothing, and its overhead is the check of the presence of the cross-domain HTTP header.

This is extremely useful in CometD web applications where it is now possible to perform cross-domain long polling without using script injection (also known as the JSONP transport), and therefore removing all the downsides that the JSONP transport has (it's chattier, does not react quickly to failures, has a message size limit, uses GET instead of POST, etc.).

[[cross-origin-setup]]
==== Setup

You will need to put the `jetty-servlets.jar` file onto your classpath.
If you are creating a webapp, ensure that this jar is included in your webapp's `WEB-INF/lib`.
Or, if you are running Jetty embedded you will need to ensure that `jetty-servlets.jar` is on the execution classpath.
You can download the `jetty-servlets.jar` from the Maven Central Repository at http://central.maven.org/maven2/org/eclipse/jetty/jetty-servlets/.
It is also available as part of the Jetty distribution in the `$JETTY_HOME/lib` directory.

[[cross-origin-config]]
==== Configuration

This is a regular servlet filter that must be configured in `web.xml`.

It supports the following configuration parameters:

allowedOrigins::
A comma separated list of origins that are allowed to access the resources.
Default value is: * (all origins)
allowedMethods::
A comma separated list of HTTP methods that are allowed to be used when accessing the resources.
Default value is: GET,POST,HEAD
allowedHeaders::
A comma separated list of HTTP headers that are allowed to be specified when accessing the resources.
Default value is: X-Requested-With,Content-Type,Accept,Origin
allowCredentials::
A boolean indicating if the resource allows requests with credentials.
Default value is: true
preflightMaxAge::
The number of seconds that preflight requests can be cached by the client.
Default value is 1800 seconds (30 minutes)
chainPreflight::
If true preflight requests are chained to their target resource for normal handling (as an OPTION request).
Otherwise the filter will response to the preflight.
Default is true.
exposedHeaders::
A comma separated list of HTTP headers that are allowed to be exposed on the client.
Default value is the empty list.

A typical configuration could be:

[source, xml, subs="{sub-order}"]
----
<web-app>

    <filter>
        <filter-name>cross-origin</filter-name>
        <filter-class>org.eclipse.jetty.servlets.CrossOriginFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>cross-origin</filter-name>
        <url-pattern>/cometd/*</url-pattern>
    </filter-mapping>

</web-app>
----