com.holonplatform.auth

## Interface Realm

- All Superinterfaces:
    Authentication.AuthenticationNotifier, Authenticator<AuthenticationToken>, Authenticator.MessageAuthenticator, Authorizer<Permission>
  All Known Implementing Classes:
    DefaultRealm

      public interface Realm
      extends Authenticator<AuthenticationToken>, Authorizer<Permission>, Authenticator.MessageAuthenticator, Authentication.AuthenticationNotifier

  A Realm represents a security abstraction providing operations for principals authentication (for example login a user relying on user accounts informations) and authorization (permission check against principal grants stored in this realm).

  A Realm may be identified by name, which should be unique within the same application.

  Authentication is performed using `Authenticator` interface, but it is delegated to concrete `Authenticator` instances which must be registered in realm using `addAuthenticator(Authenticator)`.

  Authorization is performed through `Authorizer` interface, and delegated to concrete `Authorizer` instances which must be registered in realm using `addAuthorizer(Authorizer)`.

  Supports `AuthenticationToken.AuthenticationTokenResolver` registration to perform authentication requests translation into `AuthenticationToken`s.

  Extends `Authenticator.MessageAuthenticator` to support authentication using generic authentication request `Message`.

  Extends `Authentication.AuthenticationNotifier` to allow `Authentication.AuthenticationListener` registration.

  Since:
    5.0.0
  See Also:
    `Authenticator.MessageAuthenticator`, `Authentication.AuthenticationNotifier`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Realm.Builder` Builder to create `Realm` instances.

    - ### Nested classes/interfaces inherited from interface com.holonplatform.auth.Authenticator

      `Authenticator.MessageAuthenticator`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONTEXT_KEY` Default `Context` resource reference

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T extends AuthenticationToken> void` | `addAuthenticator(Authenticator<T> authenticator)` Add a concrete `Authenticator` for a specific `AuthenticationToken` type to this Realm
    `<P extends Permission> void` | `addAuthorizer(Authorizer<P> authorizer)` Add and `Authorizer` to support a specific `Permission` type
    `static Realm.Builder` | `builder()` Builder to create Realm instances
    `static Optional<Realm>` | `getCurrent()` Convenience method to obtain the current `Realm` made available as `Context` resource, using default `ClassLoader`.
    `Optional<String>` | `getName()` Get optional realm name.
    `static Realm` | `require()` Requires the current `Realm`.
    `boolean` | `supportsPermission(Class<? extends Permission> permissionType)` Returns whether this Realm supports given `Permission` type
    `boolean` | `supportsToken(Class<? extends AuthenticationToken> authenticationTokenType)` Returns whether this Realm supports given `AuthenticationToken` type (i.e. and `Authenticator` bound to given token type is registered in realm)

    - ### Methods inherited from interface com.holonplatform.auth.Authenticator

      `authenticate, create, getTokenType`

    - ### Methods inherited from interface com.holonplatform.auth.Authorizer

      `create, getPermissionType, isPermitted, isPermitted, isPermitted, isPermittedAny, isPermittedAny, isPermittedAny`

    - ### Methods inherited from interface com.holonplatform.auth.Authenticator.MessageAuthenticator

      `addAuthenticationTokenResolver, authenticate, getResolversForMessageType, supportsMessage`

    - ### Methods inherited from interface com.holonplatform.auth.Authentication.AuthenticationNotifier

      `addAuthenticationListener, removeAuthenticationListener`

- - ### Field Detail

    - #### CONTEXT_KEY

          static final String CONTEXT_KEY

      Default `Context` resource reference

  - ### Method Detail

    - #### getName

          Optional<String> getName()

      Get optional realm name. Should be unique at application level.
      Returns:
        Realm name or an empty Optional if not available

    - #### supportsToken

          boolean supportsToken(Class<? extends AuthenticationToken> authenticationTokenType)

      Returns whether this Realm supports given `AuthenticationToken` type (i.e. and `Authenticator` bound to given token type is registered in realm)
      Parameters:
        `authenticationTokenType` - AuthenticationToken type
      Returns:
        `true` if Realm supports given AuthenticationToken type

    - #### addAuthenticator

          <T extends AuthenticationToken> void addAuthenticator(Authenticator<T> authenticator)

      Add a concrete `Authenticator` for a specific `AuthenticationToken` type to this Realm
      Type Parameters:
        `T` - Authentication token type
      Parameters:
        `authenticator` - The `Authenticator` to add (not null)

    - #### supportsPermission

          boolean supportsPermission(Class<? extends Permission> permissionType)

      Returns whether this Realm supports given `Permission` type
      Parameters:
        `permissionType` - Permission type
      Returns:
        `true` if this Realm supports given Permission type

    - #### addAuthorizer

          <P extends Permission> void addAuthorizer(Authorizer<P> authorizer)

      Add and `Authorizer` to support a specific `Permission` type
      Type Parameters:
        `P` - Permission type
      Parameters:
        `authorizer` - The `Authorizer` to add (not null)

    - #### builder

          static Realm.Builder builder()

      Builder to create Realm instances
      Returns:
        RealmBuilder

    - #### getCurrent

          static Optional<Realm> getCurrent()

      Convenience method to obtain the current `Realm` made available as `Context` resource, using default `ClassLoader`.

      See `Context.resource(String, Class)` for details about context resources availability conditions.

      Returns:
        Optional Realm, empty if not available as context resource

    - #### require

          static Realm require()

      Requires the current `Realm`. If not available using `getCurrent()`, an `IllegalStateException` is thrown.
      Returns:
        Current Realm
      Throws:
        `IllegalStateException` - Realm is not available as a `Context` resource

Copyright © 2019 The Holon Platform. All rights reserved.