Package org.apache.tapestry5.services

# Interface Environment

All Known Implementing Classes:
  `EnvironmentImpl`

public interface Environment
Provides access to environment objects, which are almost always provided to enclosed components by enclosing components. Environmental services are a form of very late binding. The Environment acts like a collection of stacks. Each stack contains environmental objects of a given type. Most often, a stack has zero or one elements, but on occasion, a particular component will push an override onto the stack for the benefit of the components it encloses.

See Also:
  - `Environmental`
  - `EnvironmentalShadowBuilder`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cloak()`
  Deprecated.
  Deprecated in 5.4 with no replacement; not longer used by Tapestry.
  `void`
  `decloak()`
  Deprecated.
  Deprecated in 5.4 with no replacement; not longer used by Tapestry.
  `<T> T`
  `peek(Class<T> type)`
  Peeks at the current top of the indicated stack.
  `<T> T`
  `peekRequired(Class<T> type)`
  Peeks at the current top of the indicated stack (which must have a non-null value).
  `<T> T`
  `pop(Class<T> type)`
  Removes and returns the top environmental object of the selected type.
  `<T> T`
  `push(Class<T> type, T instance)`
  Pushes a new service onto the stack.

- ## Method Details

  - ### peek

    <T> T peek(Class<T> type)
    Peeks at the current top of the indicated stack.
    Type Parameters:
      `T` - the type of environmental object
    Parameters:
      `type` - class used to select the object
    Returns:
      the current object of that type, or null if no service of that type has been added

  - ### peekRequired

    <T> T peekRequired(Class<T> type)
    Peeks at the current top of the indicated stack (which must have a non-null value).
    Type Parameters:
      `T` - the type of environmental object
    Parameters:
      `type` - class used to select the object
    Returns:
      the current object of the specified type
    Throws:
      `RuntimeException` - if no service of that type has been added

  - ### pop

    <T> T pop(Class<T> type)
    Removes and returns the top environmental object of the selected type.
    Type Parameters:
      `T` - the type of environmental object
    Parameters:
      `type` - class used to select the object
    Returns:
      the object just removed
    Throws:
      `NoSuchElementException` - if the environmental stack (for the specified type) is empty

  - ### push

    <T> T push(Class<T> type, T instance)
    Pushes a new service onto the stack. The old service at the top of the stack is returned (it may be null).
    Type Parameters:
      `T` - the type of environmental object
    Parameters:
      `type` - class used to select the object
      `instance` - the service object
    Returns:
      the previous top service

  - ### cloak

    void cloak()
    Deprecated.
    Deprecated in 5.4 with no replacement; not longer used by Tapestry.
    Hides all current environment values, making the Environment object appear empty, until a call to `decloak()`} restores the original state.
    Since:
      5.3
    See Also:
      - `TapestryConstants.RESPONSE_RENDERER`

  - ### decloak

    void decloak()
    Deprecated.
    Deprecated in 5.4 with no replacement; not longer used by Tapestry.
    Restores state previously hidden by `cloak()`}.
    Since:
      5.3
    See Also:
      - `TapestryConstants.RESPONSE_RENDERER`