Class ELContext
- java.lang.Object
-
- jakarta.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
, anELContext
must be provided. TheELContext
holds:- a reference to
FunctionMapper
that will be used to resolve Jakarta Expression Language Functions. This is used only in parsing. - a reference to
VariableMapper
that will be used to resolve Jakarta Expression Language 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, Jakarta Server Pages and Jakarta Faces resolvers need access to ajakarta.servlet.jsp.JspContext
and ajakarta.faces.context.FacesContext
, respectively.When used in a web container, the creation of
ELContext
objects is controlled through the underlying technology. For example, in Jakarta Server Pages theJspContext.getELContext()
factory method is used. Some technologies provide the ability to add anELContextListener
so that applications and frameworks can ensure their own context objects are attached to any newly createdELContext
.When used in a stand-alone environment,
StandardELContext
provides a defaultELContext
, which is managed and modified byELManager
.Because it stores state during expression evaluation, an
ELContext
object is not thread-safe. Care should be taken to never share anELContext
instance between two or more threads.- Since:
- Jakarta Expression Language 2.1 and Jakarta Expression Language 3.0
- See Also:
ELContextListener
,ELContextEvent
,ELResolver
,FunctionMapper
,VariableMapper
,ImportHandler
,LambdaExpression
,StandardELContext
-
-
Constructor Summary
Constructors Constructor Description ELContext()
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
addEvaluationListener(EvaluationListener listener)
Registers an evaluation listener to the ELContext.<T> T
convertToType(Object obj, Class<T> 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 theELResolver
associated with this context.List<EvaluationListener>
getEvaluationListeners()
Returns the list of registered evaluation listeners.abstract FunctionMapper
getFunctionMapper()
Retrieves theFunctionMapper
associated with thisELContext
.ImportHandler
getImportHandler()
Retrieves theImportHandler
associated with thisELContext
.Object
getLambdaArgument(String arg)
Retrieves the Lambda argument associated with a formal parameter.Locale
getLocale()
Get theLocale
stored by a previous invocation tosetLocale(java.util.Locale)
.abstract VariableMapper
getVariableMapper()
Retrieves theVariableMapper
associated with thisELContext
.boolean
isLambdaArgument(String arg)
Inquires if the name is a LambdaArgumentboolean
isPropertyResolved()
Returns whether anELResolver
has successfully resolved a given (base, property) pair.void
notifyAfterEvaluation(String expr)
Notifies the listeners after an Jakarta Expression Language expression is evaluatedvoid
notifyBeforeEvaluation(String expr)
Notifies the listeners before an Jakarta Expression Language expression is evaluatedvoid
notifyPropertyResolved(Object base, Object property)
Notifies the listeners when the (base, property) pair is resolvedvoid
putContext(Class<?> key, Object contextObject)
Associates a context object with thisELContext
.void
setLocale(Locale locale)
Sets theLocale
for this instance.void
setPropertyResolved(boolean resolved)
Called to indicate that aELResolver
has successfully resolved a given (base, property) pair.void
setPropertyResolved(Object base, Object property)
Called to indicate that aELResolver
has successfully resolved a given (base, property) pair and to notify theEvaluationListener
s.
-
-
-
Method Detail
-
setPropertyResolved
public void setPropertyResolved(boolean resolved)
Called to indicate that aELResolver
has successfully resolved a given (base, property) pair. UsesetPropertyResolved(Object, Object)
if resolved is true and to notifyEvaluationListener
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 aELResolver
has successfully resolved a given (base, property) pair and to notify theEvaluationListener
s.The
CompositeELResolver
checks this property to determine whether it should consider or skip other component resolvers.- Parameters:
base
- The base objectproperty
- The property object- Since:
- Jakarta Expression Language 3.0
- See Also:
CompositeELResolver
-
isPropertyResolved
public boolean isPropertyResolved()
Returns whether anELResolver
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 thisELContext
.The
ELContext
maintains a collection of context objects relevant to the evaluation of an expression. These context objects are used byELResolver
s. This method is used to add a context object to that collection.By convention, the
contextObject
will be of the type specified by thekey
. 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 byELResolver
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 thisELContext
.- 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 theELResolver
associated with this context.The
ELContext
maintains a reference to theELResolver
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 theELResolver
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 theImportHandler
associated with thisELContext
.- Returns:
- The import handler to manage imports of classes and packages.
- Since:
- Jakarta Expression Language 3.0
-
getFunctionMapper
public abstract FunctionMapper getFunctionMapper()
Retrieves theFunctionMapper
associated with thisELContext
.- Returns:
- The function mapper to be consulted for the resolution of Jakarta Expression Language functions.
-
getLocale
public Locale getLocale()
Get theLocale
stored by a previous invocation tosetLocale(java.util.Locale)
. If this method returns nonnull
, thisLocale
must be used for all localization needs in the implementation. TheLocale
must not be cached to allow for applications that changeLocale
dynamically.- Returns:
- The
Locale
in which this instance is operating. Used primarily for message localization.
-
setLocale
public void setLocale(Locale locale)
Sets theLocale
for this instance.This method may be called by the party creating the instance, such as Jakarta Faces or Jakarta Server Pages, to enable the Jakarta Expression Language implementation to provide localized messages to the user. If no
Locale
is set, the implementation must use the locale returned byLocale.getDefault( )
.- Parameters:
locale
- the locale for this instance
-
getVariableMapper
public abstract VariableMapper getVariableMapper()
Retrieves theVariableMapper
associated with thisELContext
.- Returns:
- The variable mapper to be consulted for the resolution of Jakarta Expression Language variables.
-
addEvaluationListener
public void addEvaluationListener(EvaluationListener listener)
Registers an evaluation listener to the ELContext.- Parameters:
listener
- The listener to be added.- Since:
- Jakarta Expression Language 3.0
-
getEvaluationListeners
public List<EvaluationListener> getEvaluationListeners()
Returns the list of registered evaluation listeners.- Returns:
- The list of registered evaluation listeners.
- Since:
- Jakarta Expression Language 3.0
-
notifyBeforeEvaluation
public void notifyBeforeEvaluation(String expr)
Notifies the listeners before an Jakarta Expression Language expression is evaluated- Parameters:
expr
- The Jakarta Expression Language expression string to be evaluated
-
notifyAfterEvaluation
public void notifyAfterEvaluation(String expr)
Notifies the listeners after an Jakarta Expression Language expression is evaluated- Parameters:
expr
- The Jakarta Expression Language 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 objectproperty
- 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:
- Jakarta Expression Language 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:
- Jakarta Expression Language 3.0
-
exitLambdaScope
public void exitLambdaScope()
Exits the Lambda expression evaluation. The Lambda argument map that was previously installed is removed.- Since:
- Jakarta Expression Language 3.0
-
convertToType
public <T> T convertToType(Object obj, Class<T> targetType)
Converts an object to a specific type. If a custom converter in theELResolver
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.- Returns:
- object converted to
targetType
- Throws:
ELException
- thrown if errors occur.- Since:
- Jakarta Expression Language 3.0
-
-