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

    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 Configuration with CORS in Helidon MP
:toc:
:toc-placement: preamble
:h1Prefix: MP
:pagename: cors-mp-configuration
:description: Helidon MP CORS Configuration
:keywords: helidon, java, cors, mp, microprofile, configuration
:javadoc-base-url-api: {javadoc-base-url}io.helidon.microprofile.cors/io/helidon/microprofile/cors
:javadoc-base-url-webserver: {javadoc-base-url}io.helidon.webserver/io/helidon/webserver
: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
:cors-se: ../../se/cors
:cors-se-intro: {cors-se}/01_introduction.adoc
:cors-se-api: {cors-se}/02_using-the-api.adoc
:cors-se-config: {cors-se}/03_using-configuration.adoc
:cors-config-table-src: {cors-se-api}
:cors-mapped-config-src: {cors-se-config}
:mp-pages-ref-prefix: mp/cors
:mp-cors-builtin-services-ref: {mp-pages-ref-prefix}/04_support-in-builtin-services.adoc
:mapped-config-top-key: cors
:mapped-config-id-callout: The unique identifier for this mapped CORS config section must be `cors`.
:common-page-prefix-inc: ../../shared/cors/common_shared.adoc
:config-table-methods-column-explainer: the annotation parameters
:config-table-methods-column-header: Annotation Parameter
:basic-table-intro: The table below lists the parameters for the `@CrossOriginConfig` annotation and the configuration keys that identify the CORS characteristics.
:helidon-variant: MP

Your application code establishes the CORS behavior of your endpoints using the `@CrossOrigin` annotation.
You and your users can override that behavior, as well as the CORS behavior of the built-in services,
using MicroProfile configuration.

include::{common-page-prefix-inc}[tag=cors-configuration-formats-intro]

include::{common-page-prefix-inc}[tag=basic-cross-origin-config]

=== Understanding the Mapped Cross-Origin Configuration Format

In Helidon MP, you use
the mapped cross-origin configuration format.

// We want to use
// include::{cors-mapped-config-src}[tag=mapped-config]
// and assign an attribute for the callout 1 text. But because the MP value uses backticks for monospaced
// text, we'd have to be a little clever in the original callout. And that cleverness works when
// the document is rendered in our editors, and even when using asciidoctor to HTML, but not
// to our site.
include::{common-page-prefix-inc}[tag=mapped-config-prefix]
<1> The unique identifier for this mapped CORS config section must be `cors`.
include::{common-page-prefix-inc}[tag=mapped-config-suffix]

== Specifying Override Values in Configuration 
In configuration, you can specify the same CORS-related attributes that you specify using the `@CrossOrigin` annotation.

The following example shows how you can express configuration similar to that shown
previously using the mapped cross-origin configuration format.
Here, the example uses properties-file syntax
in your applications's `META-INF/microprofile-config.properties` file. Note that the top-level config key
must be `cors`.

[source,properties]
----
cors.paths.0.path-pattern = /greeting
cors.paths.0.allow-origins = http://foo.com, http://there.com, http://other.com
cors.paths.0.allow-methods = PUT, DELETE
cors.paths.1.path-pattern = /
cors.paths.1.allow-methods = GET, HEAD, OPTIONS, POST
----

NOTE: Remember that if you set configuration in a file that you include as part of your application JAR file, then you need to
rebuild and restart your application for any changes to take effect.

== Next Steps
* Use these same configuration techniques to control the behavior of the CORS-enabled
built-in services. <<{mp-cors-builtin-services-ref},Learn more.>>

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