blob: df5dd636f1a0af9e2686f8679737bd9a8e3e2cce [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<TITLE>
org.apache.cxf.rs.security.cors (Apache CXF Bundle Jar 2.7.0 API)
</TITLE>
<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../../stylesheet.css" TITLE="Style">
<SCRIPT type="text/javascript">
function windowTitle()
{
if (location.href.indexOf('is-external=true') == -1) {
parent.document.title="org.apache.cxf.rs.security.cors (Apache CXF Bundle Jar 2.7.0 API)";
}
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>
</HEAD>
<BODY BGCOLOR="white" onload="windowTitle();">
<HR>
<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
Apache CXF API</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../../../org/apache/cxf/rs/security/common/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<A HREF="../../../../../../org/apache/cxf/rs/security/oauth/client/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../../../../index.html?org/apache/cxf/rs/security/cors/package-summary.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->
<HR>
<H2>
Package org.apache.cxf.rs.security.cors
</H2>
CORS
<P>
<B>See:</B>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#package_description"><B>Description</B></A>
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Class Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/cxf/rs/security/cors/CorsHeaderConstants.html" title="class in org.apache.cxf.rs.security.cors">CorsHeaderConstants</A></B></TD>
<TD>Headers used to implement http://www.w3.org/TR/cors/.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/cxf/rs/security/cors/CrossOriginResourceSharingFilter.html" title="class in org.apache.cxf.rs.security.cors">CrossOriginResourceSharingFilter</A></B></TD>
<TD>A single class that provides both an input and an output filter for CORS, following
http://www.w3.org/TR/cors/.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Annotation Types Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/cxf/rs/security/cors/CrossOriginResourceSharing.html" title="annotation in org.apache.cxf.rs.security.cors">CrossOriginResourceSharing</A></B></TD>
<TD>Attach <a href="http://www.w3.org/TR/cors/">CORS</a> information
to a resource.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../../org/apache/cxf/rs/security/cors/LocalPreflight.html" title="annotation in org.apache.cxf.rs.security.cors">LocalPreflight</A></B></TD>
<TD>Controls the implementation of preflight processing
on an OPTIONS method.</TD>
</TR>
</TABLE>
&nbsp;
<P>
<A NAME="package_description"><!-- --></A><H2>
Package org.apache.cxf.rs.security.cors Description
</H2>
<P>
<h1>CORS</h1>
<p>This package provides a filter to assist applications in implementing Cross Origin Resource Sharing,
as described in the <a href="http://www.w3.org/TR/cors">CORS specification</a>.
</p>
<h2>CORS Access Model</h2>
<p>
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 <em>implemented on the client</em> that, by default,
prohibit cross-origin access.
</p>
<p>
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. <CODE>CrossOriginResourceSharingFilter</CODE> adds these headers to your service's
responses based on rules that you configure.
</p>
<h2>CORS Resource Model (versus JAX-RS)</h2>
<p>
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:
<ul>
<li>URI</li>
<li>HTTP Method</li>
<li>Content-Type and Accept HTTP headers</li>
</ul>
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.
</p>
<h2>Simple and Preflight requests</h2>
<p>The CORS specification differentiates two kinds of HTTP requests: <em>simple</em> and <em>not simple</em>. (See the specification
for the definition.) For a simple request, the client simply
sends the request to the service, and then looks for the <tt>Access-Control-</tt> headers to indicate whether the server has explicitly granted
cross-origin access. For a non-simple request, the client sends a so-called <em>preflight</em> request and waits for a response before
issuing the original request.
<h2>Configuration via Annotation</h2>
<p>
One way to control the behavior of the filter is the @<CODE>CrossOriginResourceSharing</CODE> 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.
</p>
<p>
If all the methods of a class can share a common policy, you can attach a single @<CODE>CrossOriginResourceSharing</CODE>
to a resource class, and it will apply to all the resource implied by all of the methods.
</p>
<h2>Bean Configuration</h2>
<p>
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 <CODE>CrossOriginResourceSharingFilter</CODE> to specify the policy.
</p>
<P>
<P>
<DL>
</DL>
<HR>
<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
<TR ALIGN="center" VALIGN="top">
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-use.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
<TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1"> <A HREF="../../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
</TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
Apache CXF API</EM>
</TD>
</TR>
<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../../../org/apache/cxf/rs/security/common/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<A HREF="../../../../../../org/apache/cxf/rs/security/oauth/client/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
<A HREF="../../../../../../index.html?org/apache/cxf/rs/security/cors/package-summary.html" target="_top"><B>FRAMES</B></A> &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A> &nbsp;
&nbsp;<SCRIPT type="text/javascript">
<!--
if(window==top) {
document.writeln('<A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
}
//-->
</SCRIPT>
<NOSCRIPT>
<A HREF="../../../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>
</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->
<HR>
Apache CXF
</BODY>
</HTML>