///////////////////////////////////////////////////////////////////////////////

    Copyright (c) 2020 Oracle and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.

///////////////////////////////////////////////////////////////////////////////

= Using the Helidon MP CORS API
:toc:
:toc-placement: preamble
:h1Prefix: MP
:pagename: using-cors-in-mp
:description: Using the Helidon MP CORS API
:keywords: helidon, java, cors, mp, microprofile
:javadoc-base-url-api: {javadoc-base-url}io.helidon.microprofile.cors/io/helidon/microprofile/cors
:helidon-tag: https://github.com/oracle/helidon/tree/{helidon-version}
:quickstart-example: {helidon-tag}/examples/quickstarts/helidon-quickstart-mp
:cors-spec: https://www.w3.org/TR/cors/
:helidon-mp-cors-example: {helidon-tag}/examples/microprofile/cors
:mp-pages-ref-prefix: mp/cors
:mp-cors-config-ref: {mp-pages-ref-prefix}/03_configuration-with-cors-mp.adoc
:helidon-variant: MP
:common-page-prefix-inc: ../../shared/cors/common_shared.adoc

To enable CORS behavior for a resource in your Helidon MP application, you simply add the Helidon MP `@CrossOrigin`
annotation to a particular method in your resource class.

== Understanding the `@CrossOrigin` Annotation
You set up CORS in Helidon MP using the link:{javadoc-base-url-api}/CrossOrigin.html[`@CrossOrigin`] annotation.

The following example of the `@CrossOrigin` annotation allows the resource associated with it to be shared with the origins `\http://foo.bar` and `\http://bar.foo`
using `DELETE` or `PUT`, and permits requests to include the non-standard headers `X-foo` and `X-bar`.

[source,java]
----
@CrossOrigin(value = {"http://foo.bar", "http://bar.foo"},
             allowHeaders = {"X-foo", "X-bar"},
             allowMethods = {HttpMethod.DELETE, HttpMethod.PUT})
----




== Getting Started
To add CORS support to your Helidon MP application:

. Determine the type of cross-origin resource sharing you want to allow
 for each endpoint in your application.
. {blank}
+
--
Add a dependency on the Helidon {helidon-variant} CORS artifact to your Maven `pom.xml` file.

include::{common-page-prefix-inc}[tag=add-cors-dependency]
// tag::actual-cors-dependency[]
[source,xml,subs="attributes+"]
----
<dependency>
    <groupId>io.helidon.microprofile</groupId>
    <artifactId>helidon-microprofile-cors</artifactId>
</dependency>
----
// end::actual-cors-dependency[]
--
. Edit each JAX-RS resource class in your application to add the desired CORS behavior as described in the following sections.



== Adding CORS Support to Your Helidon MP Application
Adding CORS behavior to your Helidon MP application involves two simple changes to your application code:

. For each resource and subresource in each resource class, make sure you have a Java method annotated with
`@OPTIONS` and with the correct `@Path`. Create these methods for each resource if you do not already have them.
. To each of those methods, add a `@CrossOrigin` annotation that describes the cross-origin sharing you want
for that resource.

The Helidon MP CORS implementation automatically uses the `@CrossOrigin` annotation you add to each `@OPTIONS` method to
enforce cross-origin sharing behavior for the resource identified by that method's `@Path` annotation.

For an informal look at the reasons for applying the `@CrossOrigin` annotation to the `@OPTIONS` method, instead of another
method, see <<mp/cors/hide_why-options.adoc, Why `@OPTIONS`?>>.

== Sample Application Using the `@CrossOrigin` Annotation

In the link:{quickstart-example}[Helidon MP Quickstart application] you can change the greeting by sending a `PUT`
request to the `/greet/greeting` resource.
The example below extends the Helidon MP QuickStart application (the greeting app) to:

* Permit unrestricted sharing of the resource that returns greetings, and
* Restrict sharing of the resource that
updates the greeting so that only the origins `\http://foo.com` and `\http://there.com` can change the greeting.

[source,java]
----
@OPTIONS
@CrossOrigin() // <1>
public void options() {}

@OPTIONS
@Path("/greeting")
@CrossOrigin(allowMethods = {"PUT"}, allowOrigins = {"http://foo.com", "http://there.com"}) // <2>
public void optionsForGreeting() {}
----
<1> Uses the default cross-origin sharing, which permits sharing via all HTTP methods to all origins.
<2> Specifies sharing only via the `PUT` HTTP method and only to the two listed origins.

== Next steps

* Use MicroProfile configuration to override the CORS behavior set in
the application code. <<{mp-cors-config-ref},Learn more.>>

* See the Helidon CORS support in action by building and running the link:{helidon-mp-cors-example}[CORS example].
