Package oracle.dbtools.plugin.api.http.annotations

## Enum CrossOriginSharingPolicy

- java.lang.Object
- - java.lang.Enum<CrossOriginSharingPolicy>
  - - oracle.dbtools.plugin.api.http.annotations.CrossOriginSharingPolicy

- All Implemented Interfaces:
    `java.io.Serializable`, `java.lang.Comparable<CrossOriginSharingPolicy>`

      public enum CrossOriginSharingPolicy
      extends java.lang.Enum<CrossOriginSharingPolicy>

  ### About Cross Origin Requests

  Web Browser User Agents (Chrome, FireFox et al.) prevent web-pages from accessing resources located on hosts other than the host that served the web-page. This is called the 'Same Origin' policy and is a critical part of the browser security model. It helps prevents a malicious site stealing data or taking unauthorized actions on another site, via the browser user-agent.

  An 'Origin' is a DNS server name, plus it's protocol, plus the port that the server is listening on, the examples below each reside in a different origin:

  - `https://example.com`
  - `http://example.com` - different protocol
  - `https://www.example.com` - different DNS name
  - `https://example.com:8080` - different port

  ### About Cross Origin Resource Sharing

  For many applications, unilaterally preventing this access is prohibitive, especially when there is a trust relationship between two different origins. The Cross Origin Resource Sharing Specification (CORS) defines a protocol for web-browsers and web-servers to safely permit Cross Origin requests between origins that have reason to trust each other.

  ### About CORS and Public Resources

  A public resource is any resource served by a servlet that is NOT protected by a `Privilege`

  Because public resources are just that: public, they are enabled for CORS requests by default. In some cases it may be undesirable to make a public resource available for CORS requests, for example the resources associated with a sign-on form, this default can be overriden. Or if a servlet performs it's own authentication and authorization, it may wish to disable the automatic CORS support.

  You can disable access for the entire servlet using the `CORS` annotation or disable specific paths served by the servlet by using the `PathTemplate.cors()` property.

  #### Disabling CORS access for a servlet

       @Dispatches(@PathTemplate("/logon"))
       @CORS(CrossOriginSharingPolicy.DENY)
       @Provides
       class LogonServlet extends HttpServlet {
       ...
       }

  #### Disabling CORS access for a PathTemplate

       @Dispatches(@PathTemplate(value="/logon",cors=CrossOriginSharingPolicy.DENY))
       @Provides
       class LogonServlet extends HttpServlet {
       ...
       }

  ### About CORS and Protected Resources

  A protected resource is any resource served by a servlet that is protected by a `Privilege`

  Protected resources are also CORS enabled by default, but access to protected resources is restricted to callers providing the necessary credentials and having the required `Privilege.roles()`.

  This means that a pre-flight request against a protected resource may succeed, but the actual operation will fail because the caller lacks the required credentials or roles.

  Protected resources can deny CORS access in the same manner shown above for public resources.

  It is worth noting that any cookie based authentication mechanism cannot work safely with CORS enabled resources, because browsers always send cookies, which provides a means for Cross Site Request Forgery (CSRF) attacks. By contrast token based authorization (e.g. OAuth 2.0 ) can work safely with CORS resources, because possession of the token proves that the server can trust the caller (unless the token has been inadvertently disclosed/compromised).

  ORDS built in cookie based authentication mechanisms explicitly do not authenticate cross origin requests, however if a servlet is implementing it's own authentication/authorization mechanisms, it is crucial to remember the above point, and check for and validate any `Origin` header present in the request.

  ### Controlling Authorized Origins

  A servlet can constrain which origins are permitted to access a resource by emitting the `Access-Control-Allow-Origin` header. If the value of the header is `*` or a character for character match of the origin that made the request, the request will be CORS enabled. If the value is `null` or empty, or not a match for the request origin, the request will not be CORS enabled. If this header is present in the response, then the above behaviour overrides the behaviour prescribed by the servlet's `CrossOriginSharingPolicy`. If the header is not present in the response then the `CrossOriginSharingPolicy` takes precedent.

  ### About Preflight Requests

  If a servlet is CORS enabled, then preflight `OPTIONS` requests will be handled by ORDS, and will always succeed for any origin. If a servlet wishes to take finer control over pre-flight requests, then it should advertise via the `PathTemplate.methods()` property that it will handle the `OPTIONS` request itself. Note if a servlet does handle `OPTIONS` itself then the automatic CORS support is disabled, and the servlet is completely responsible for supporting (or not supporting) the CORS protocol correctly.

  ### About Automatic CORS Support

  If a servlet indicates via the `ALLOW` setting that it supports CORS then, ORDS will automatically:

  - handle all CORS preflight `OPTIONS` requests
  - Add `Access-Control-Allow-Credentials` header with a value of `true` to the response.
  - Add `Access-Control-Expose-Headers` header enumerating all the headers in the response.
  Author:
    cdivilly
  See Also:
    Cross Origin Resource Sharing Specification

- - ### Enum Constant Summary

    Enum Constants
    Enum Constant | Description
    --- | ---
    `ALLOW` | The resource can be accessed via `CORS`.
    `DENY` | The resource may not be accessed via `CORS`
    `INHERIT` | Inherit the `CrossOriginSharingPolicy` from the containing object

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static CrossOriginSharingPolicy` | `value​(java.lang.String text)` | Determine the `CrossOriginSharingPolicy` for the specified textual representation
    `static CrossOriginSharingPolicy` | `valueOf​(java.lang.String name)` | Returns the enum constant of this type with the specified name.
    `static CrossOriginSharingPolicy[]` | `values()` | Returns an array containing the constants of this enum type, in the order they are declared.

    - ### Methods inherited from class java.lang.Enum

      `clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

    - ### Methods inherited from class java.lang.Object

      `getClass, notify, notifyAll, wait, wait, wait`

- - ### Enum Constant Detail

    - #### ALLOW

          public static final CrossOriginSharingPolicy ALLOW

      The resource can be accessed via `CORS`.

    - #### DENY

          public static final CrossOriginSharingPolicy DENY

      The resource may not be accessed via `CORS`

    - #### INHERIT

          public static final CrossOriginSharingPolicy INHERIT

      Inherit the `CrossOriginSharingPolicy` from the containing object

  - ### Method Detail

    - #### values

          public static CrossOriginSharingPolicy[] values()

      Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:

          for (CrossOriginSharingPolicy c : CrossOriginSharingPolicy.values())
              System.out.println(c);

      Returns:
        an array containing the constants of this enum type, in the order they are declared

    - #### valueOf

          public static CrossOriginSharingPolicy valueOf​(java.lang.String name)

      Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
      Parameters:
        `name` - the name of the enum constant to be returned.
      Returns:
        the enum constant with the specified name
      Throws:
        `java.lang.IllegalArgumentException` - if this enum type has no constant with the specified name
        `java.lang.NullPointerException` - if the argument is null

    - #### value

          public static CrossOriginSharingPolicy value​(java.lang.String text)

      Determine the `CrossOriginSharingPolicy` for the specified textual representation
      Parameters:
        `text` - The textual representation of the `CrossOriginSharingPolicy`
      Returns:
        `DENY` if the textual value equals (case insensitive) `DENY`, `ALLOW` otherwise