org.appng.api

## Interface Environment

- All Known Implementing Classes:
    DefaultEnvironment

      public interface Environment

  The `Environment` is able to set, read and remove attributes of a certain `Scope`. The main purposes are:
  - keeping track of the current `Subject` via `getSubject()`
  - providing informations about the current `Locale` and `TimeZone` via `getLocale()` and `getTimeZone()`
  - allowing to share attributes between multiple applications (using `Scope.SESSION` and `Scope.SITE`)
  - keeping track of platform-wide configuration parameters ( `Scope.PLATFORM` and `Application`s where `Application.isPrivileged()` is `true`)

Author:
  Matthias Müller
See Also:
  `Scope`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T> T` | `getAttribute(Scope scope, String name)` Returns the attribute with the given name for the given `Scope`.
    `String` | `getAttributeAsString(Scope scope, String name)` Returns the string-representation of an attribute, calling `toString()` on the resulting object.
    `default ScopedEnvironment` | `getEnvironment(Scope scope)` Returns a `ScopedEnvironment` for the given `Scope`
    `Locale` | `getLocale()` Returns the current `Locale`.
    `default Site` | `getSite()` Returns the current `Site`, if this environment has been created from a `HttpServletRequest`
    `Subject` | `getSubject()` Returns the current `Subject`.
    `TimeZone` | `getTimeZone()` Returns the current `TimeZone`.
    `void` | `init(javax.servlet.ServletContext context, javax.servlet.http.HttpSession session, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, String host)` Deprecated. no replacement
    `boolean` | `isSubjectAuthenticated()` Returns `true` if the current `Subject` is authenticated, `false` otherwise
    `Set<String>` | `keySet(Scope scope)` Returns a `Set` of all attribute names for the given `Scope`
    `<T> T` | `removeAttribute(Scope scope, String name)` Removes the attribute with the given name from the given `Scope` and returns it.
    `void` | `setAttribute(Scope scope, String name, Object value)` Sets an attribute for the given `Scope` to the given value.

- - ### Method Detail

    - #### getEnvironment

          default ScopedEnvironment getEnvironment(Scope scope)

      Returns a `ScopedEnvironment` for the given `Scope`
      Parameters:
        `scope` - the `Scope` to use
      Returns:
        the `ScopedEnvironment`, if scope is available, `null` otherwise.

    - #### setAttribute

          void setAttribute(Scope scope,
                            String name,
                            Object value)

      Sets an attribute for the given `Scope` to the given value.
      Parameters:
        `scope` - the `Scope` of the attribute to set
        `name` - the name of the attribute to set
        `value` - the attribute to set

    - #### getAttribute

          <T> T getAttribute(Scope scope,
                             String name)

      Returns the attribute with the given name for the given `Scope`.
      Parameters:
        `scope` - the `Scope` of the attribute to get
        `name` - the name of the attribute to get
      Returns:
        the attribute of the desired type, or `null` if the attribute does not exist in the given `Scope`

    - #### removeAttribute

          <T> T removeAttribute(Scope scope,
                                String name)

      Removes the attribute with the given name from the given `Scope` and returns it.
      Parameters:
        `scope` - the `Scope` of the attribute to remove
        `name` - the name of the attribute to remove
      Returns:
        the attribute of the desired type, or `null` if the attribute does not exist in the given `Scope`

    - #### getAttributeAsString

          String getAttributeAsString(Scope scope,
                                      String name)

      Returns the string-representation of an attribute, calling `toString()` on the resulting object.
      Parameters:
        `scope` - the `Scope` of the attribute to get
        `name` - the name of the attribute to get
      Returns:
        the string-representation of the attribute, or `null` if the attribute does not exist in the given `Scope`

    - #### keySet

          Set<String> keySet(Scope scope)

      Returns a `Set` of all attribute names for the given `Scope`
      Parameters:
        `scope` - the `Scope` the get the attribute names for
      Returns:
        a `Set` containing all attribute names, or `null` if the `Scope` is not available

    - #### getSubject

          Subject getSubject()

      Returns the current `Subject`.
      Returns:
        the `Subject`, if present

    - #### getLocale

          Locale getLocale()

      Returns the current `Locale`. If a `Subject` is logged in, a `Locale` is returned that represent the language of the `Subject` via `Account.getLanguage()`. If no `Subject` is present, the default-`Locale` from the `Site` is used.
      Returns:
        the `Locale`

    - #### getTimeZone

          TimeZone getTimeZone()

      Returns the current `TimeZone`. If a `Subject` is present (no matter whether it is logged in or not), `Account.getTimeZone()` is being returned. If no `Subject` is present, the default-`TimeZone` from the `Site` is used.
      Returns:
        the `TimeZone`

    - #### isSubjectAuthenticated

          boolean isSubjectAuthenticated()

      Returns `true` if the current `Subject` is authenticated, `false` otherwise
      Returns:
        `true` if the current `Subject` is authenticated, `false` otherwise

    - #### init

          @Deprecated
          void init(javax.servlet.ServletContext context,
                                javax.servlet.http.HttpSession session,
                                javax.servlet.ServletRequest request,
                                javax.servlet.ServletResponse response,
                                String host)

      Deprecated. no replacement
      Initializes the `Environment`.
      Parameters:
        `context` - a `ServletContext`
        `session` - a `HttpSession`
        `request` - a `ServletRequest`
        `response` - a `ServletResponse`
        `host` - the host for the site-`Scope`
      Throws:
        `IllegalStateException` - if this `Environment` already has been initialized

    - #### getSite

          default Site getSite()

      Returns the current `Site`, if this environment has been created from a `HttpServletRequest`
      Returns:
        the site
      Since:
        1.25

Copyright © 2011–2023 aiticon GmbH. All rights reserved.