javax.el

## Class ELContext

- java.lang.Object
- - javax.el.ELContext

- Direct Known Subclasses:
    FaceletContext, StandardELContext

      public abstract class ELContext
      extends Object

  Context information for expression parsing and evaluation.

  To parse or evaluate an `Expression`, an `ELContext` must be provided. The `ELContext` holds:

  - a reference to `FunctionMapper` that will be used to resolve EL Functions. This is used only in parsing.
  - a reference to `VariableMapper` that will be used to resolve EL Variables. This is used only in parsing.
  - a reference to the base `ELResolver` that will be consulted to resolve model objects and their properties
  - a collection of all the relevant context objects for use by `ELResolver`s
  - state information during the evaluation of an expression, such as whether a property has been resolved yet
  - a reference to `ImportHandler` that will be consulted to resolve classes that have been imported
  - a reference to the arguments for the active `LambdaExpression`s
  - a reference to the list of registered evaluation listeners

  The collection of context objects is necessary because each `ELResolver` may need access to a different context object. For example, JSP and Faces resolvers need access to a `JspContext` and a `FacesContext`, respectively.

  When used in a web container, the creation of `ELContext` objects is controlled through the underlying technology. For example, in JSP the `JspContext.getELContext()` factory method is used. Some technologies provide the ability to add an `ELContextListener` so that applications and frameworks can ensure their own context objects are attached to any newly created `ELContext`.

  When used in a stand-alone environment, `StandardELContext` provides a default `ELContext`, which is managed and modified by `ELManager`.

  Because it stores state during expression evaluation, an `ELContext` object is not thread-safe. Care should be taken to never share an `ELContext` instance between two or more threads.

  Since:
    EL 2.1 and EL 3.0
  See Also:
    `ELContextListener`, `ELContextEvent`, `ELResolver`, `FunctionMapper`, `VariableMapper`, `ImportHandler`, `LambdaExpression`, `StandardELContext`, `JspContext`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ELContext()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addEvaluationListener(EvaluationListener listener)` Registers an evaluation listener to the ELContext.
    `Object` | `convertToType(Object obj, Class<?> targetType)` Converts an object to a specific type.
    `void` | `enterLambdaScope(Map<String,Object> args)` Installs a Lambda argument map, in preparation for the evaluation of a Lambda expression.
    `void` | `exitLambdaScope()` Exits the Lambda expression evaluation.
    `Object` | `getContext(Class key)` Returns the context object associated with the given key.
    `abstract ELResolver` | `getELResolver()` Retrieves the `ELResolver` associated with this context.
    `List<EvaluationListener>` | `getEvaluationListeners()` Returns the list of registered evaluation listeners.
    `abstract FunctionMapper` | `getFunctionMapper()` Retrieves the `FunctionMapper` associated with this `ELContext`.
    `ImportHandler` | `getImportHandler()` Retrieves the `ImportHandler` associated with this `ELContext`.
    `Object` | `getLambdaArgument(String arg)` Retrieves the Lambda argument associated with a formal parameter.
    `Locale` | `getLocale()` Get the `Locale` stored by a previous invocation to `setLocale(java.util.Locale)`.
    `abstract VariableMapper` | `getVariableMapper()` Retrieves the `VariableMapper` associated with this `ELContext`.
    `boolean` | `isLambdaArgument(String arg)` Inquires if the name is a LambdaArgument
    `boolean` | `isPropertyResolved()` Returns whether an `ELResolver` has successfully resolved a given (base, property) pair.
    `void` | `notifyAfterEvaluation(String expr)` Notifies the listeners after an EL expression is evaluated
    `void` | `notifyBeforeEvaluation(String expr)` Notifies the listeners before an EL expression is evaluated
    `void` | `notifyPropertyResolved(Object base, Object property)` Notifies the listeners when the (base, property) pair is resolved
    `void` | `putContext(Class key, Object contextObject)` Associates a context object with this `ELContext`.
    `void` | `setLocale(Locale locale)` Sets the `Locale` for this instance.
    `void` | `setPropertyResolved(boolean resolved)` Called to indicate that a `ELResolver` has successfully resolved a given (base, property) pair.
    `void` | `setPropertyResolved(Object base, Object property)` Called to indicate that a `ELResolver` has successfully resolved a given (base, property) pair and to notify the `EvaluationListener`s.

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

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ELContext

          public ELContext()

  - ### Method Detail

    - #### setPropertyResolved

          public void setPropertyResolved(boolean resolved)

      Called to indicate that a `ELResolver` has successfully resolved a given (base, property) pair. Use `setPropertyResolved(Object, Object)` if resolved is true and to notify `EvaluationListener`s.

      The `CompositeELResolver` checks this property to determine whether it should consider or skip other component resolvers.

      Parameters:
        `resolved` - true if the property has been resolved, or false if not.
      See Also:
        `CompositeELResolver`

    - #### setPropertyResolved

          public void setPropertyResolved(Object base,
                                 Object property)

      Called to indicate that a `ELResolver` has successfully resolved a given (base, property) pair and to notify the `EvaluationListener`s.

      The `CompositeELResolver` checks this property to determine whether it should consider or skip other component resolvers.

      Parameters:
        `base` - The base object
        `property` - The property object
      Since:
        EL 3.0
      See Also:
        `CompositeELResolver`

    - #### isPropertyResolved

          public boolean isPropertyResolved()

      Returns whether an `ELResolver` has successfully resolved a given (base, property) pair.

      The `CompositeELResolver` checks this property to determine whether it should consider or skip other component resolvers.

      Returns:
        true if the property has been resolved, or false if not.
      See Also:
        `CompositeELResolver`

    - #### putContext

          public void putContext(Class key,
                        Object contextObject)

      Associates a context object with this `ELContext`.

      The `ELContext` maintains a collection of context objects relevant to the evaluation of an expression. These context objects are used by `ELResolver`s. This method is used to add a context object to that collection.

      By convention, the `contextObject` will be of the type specified by the `key`. However, this is not required and the key is used strictly as a unique identifier.

      Parameters:
        `key` - The key used by an @{link ELResolver} to identify this context object.
        `contextObject` - The context object to add to the collection.
      Throws:
        `NullPointerException` - if key is null or contextObject is null.

    - #### getContext

          public Object getContext(Class key)

      Returns the context object associated with the given key.

      The `ELContext` maintains a collection of context objects relevant to the evaluation of an expression. These context objects are used by `ELResolver`s. This method is used to retrieve the context with the given key from the collection.

      By convention, the object returned will be of the type specified by the `key`. However, this is not required and the key is used strictly as a unique identifier.

      Parameters:
        `key` - The unique identifier that was used to associate the context object with this `ELContext`.
      Returns:
        The context object associated with the given key, or null if no such context was found.
      Throws:
        `NullPointerException` - if key is null.

    - #### getELResolver

          public abstract ELResolver getELResolver()

      Retrieves the `ELResolver` associated with this context.

      The `ELContext` maintains a reference to the `ELResolver` that will be consulted to resolve variables and properties during an expression evaluation. This method retrieves the reference to the resolver.

      Once an `ELContext` is constructed, the reference to the `ELResolver` associated with the context cannot be changed.

      Returns:
        The resolver to be consulted for variable and property resolution during expression evaluation.

    - #### getImportHandler

          public ImportHandler getImportHandler()

      Retrieves the `ImportHandler` associated with this `ELContext`.
      Returns:
        The import handler to manage imports of classes and packages.
      Since:
        EL 3.0

    - #### getFunctionMapper

          public abstract FunctionMapper getFunctionMapper()

      Retrieves the `FunctionMapper` associated with this `ELContext`.
      Returns:
        The function mapper to be consulted for the resolution of EL functions.

    - #### getLocale

          public Locale getLocale()

      Get the `Locale` stored by a previous invocation to `setLocale(java.util.Locale)`. If this method returns non `null`, this `Locale` must be used for all localization needs in the implementation. The `Locale` must not be cached to allow for applications that change `Locale` dynamically.
      Returns:
        The `Locale` in which this instance is operating. Used primarily for message localization.

    - #### setLocale

          public void setLocale(Locale locale)

      Sets the `Locale` for this instance. This method may be called by the party creating the instance, such as JavaServer Faces or JSP, to enable the EL implementation to provide localized messages to the user. If no `Locale` is set, the implementation must use the locale returned by `Locale.getDefault( )`.

    - #### getVariableMapper

          public abstract VariableMapper getVariableMapper()

      Retrieves the `VariableMapper` associated with this `ELContext`.
      Returns:
        The variable mapper to be consulted for the resolution of EL variables.

    - #### addEvaluationListener

          public void addEvaluationListener(EvaluationListener listener)

      Registers an evaluation listener to the ELContext.
      Parameters:
        `listener` - The listener to be added.
      Since:
        EL 3.0

    - #### getEvaluationListeners

          public List<EvaluationListener> getEvaluationListeners()

      Returns the list of registered evaluation listeners.
      Returns:
        The list of registered evaluation listeners.
      Since:
        EL 3.0

    - #### notifyBeforeEvaluation

          public void notifyBeforeEvaluation(String expr)

      Notifies the listeners before an EL expression is evaluated
      Parameters:
        `expr` - The EL expression string to be evaluated

    - #### notifyAfterEvaluation

          public void notifyAfterEvaluation(String expr)

      Notifies the listeners after an EL expression is evaluated
      Parameters:
        `expr` - The EL expression string that has been evaluated

    - #### notifyPropertyResolved

          public void notifyPropertyResolved(Object base,
                                    Object property)

      Notifies the listeners when the (base, property) pair is resolved
      Parameters:
        `base` - The base object
        `property` - The property Object

    - #### isLambdaArgument

          public boolean isLambdaArgument(String arg)

      Inquires if the name is a LambdaArgument
      Parameters:
        `arg` - A possible Lambda formal parameter name
      Returns:
        true if arg is a LambdaArgument, false otherwise.

    - #### getLambdaArgument

          public Object getLambdaArgument(String arg)

      Retrieves the Lambda argument associated with a formal parameter. If the Lambda expression is nested within other Lambda expressions, the arguments for the current Lambda expression is first searched, and if not found, the arguments for the immediate nesting Lambda expression then searched, and so on.
      Parameters:
        `arg` - The formal parameter for the Lambda argument
      Returns:
        The object associated with formal parameter. Null if no object has been associated with the parameter.
      Since:
        EL 3.0

    - #### enterLambdaScope

          public void enterLambdaScope(Map<String,Object> args)

      Installs a Lambda argument map, in preparation for the evaluation of a Lambda expression. The arguments in the map will be in scope during the evaluation of the Lambda expression.
      Parameters:
        `args` - The Lambda arguments map
      Since:
        EL 3.0

    - #### exitLambdaScope

          public void exitLambdaScope()

      Exits the Lambda expression evaluation. The Lambda argument map that was previously installed is removed.
      Since:
        EL 3.0

    - #### convertToType

          public Object convertToType(Object obj,
                             Class<?> targetType)

      Converts an object to a specific type. If a custom converter in the `ELResolver` handles this conversion, it is used. Otherwise the standard coercions is applied.

      An `ELException` is thrown if an error occurs during the conversion.

      Parameters:
        `obj` - The object to convert.
        `targetType` - The target type for the conversion.
      Throws:
        `ELException` - thrown if errors occur.
      Since:
        EL 3.0

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.