Expression Language 3.0 API 3.0.0 · javax.el.ELProcessor

Provides an API for using EL in a stand-alone environment.

This class provides a direct and simple interface for

Evaluating EL expressions.
Assigning values to beans or setting a bean property.
Setting a ValueExpression to a EL variable.
Defining a static method as an EL function.
Defining an object instance as an EL name.

This API is not a replacement for the APIs in EL 2.2. Containers that maintains EL environments can continue to do so, without using this API.

For EL users who want to manipulate EL environments, like adding custom ELResolvers, ELManager can be used.

Scope and Life Cycle

Since it maintains the state of the EL environments, ELProcessor is not thread safe. In the simplest case, an instance can be created and destroyed before and after evaluating EL expressions. A more general usage is to use an instance of ELProcessor for a session, so that the user can configure the EL evaluation environment for that session.

Automatic Bracketing of Expressions

A note about the EL expressions strings used in the class. The strings allowed in the methods ELProcessor#getValue, ELProcessor#setValue, and ELProcessor#setVariable are limited to non-composite expressions, i.e. expressions of the form ${...} or #{...} only. Also, it is not necessary (in fact not allowed) to bracket the expression strings with ${ or #{ and } in these methods: they will be automatically bracketed. This reduces the visual cluster, without any lost of functionalities (thanks to the addition of the concatenation operator).

Example

The following code snippet illustrates the use of ELProcessor to define a bean and evaluate its property.

  ELProcessor elp = new ELProcessor();
  elp.defineBean("employee", new Employee("Charlie Brown"));
  String name = elp.eval("employee.name");

Field Summary

Modifier and Type	Field and Description
private ELManager	elManager
private ExpressionFactory	factory

Constructor Summary

Access	Constructor and Description
public	ELProcessor()

Method Summary

Modifier and Type	Method and Description
private String	bracket(String expression)
public void	defineBean(String The name of the bean name, Object The bean instance to be defined. If `null`, the name will be removed from the local bean repository. bean) Define a bean in a local bean repository, hiding other beans of the same name.
public void	defineFunction(String The namespace for the function or "" for no namesapce. prefix, String The name of the function. If empty (""), the method name is used as the function name. function, String The full Java class name that implements the function. className, String The name (specified without parenthesis) or the signature (as in the Java Language Spec) of the static method that implements the function. If the name (e.g. "sum") is given, the first declared method in class that matches the name is selected. If the signature (e.g. "int sum(int, int)" ) is given, then the declared method with the signature is selected. method) Define an EL function in the local function mapper.
public void	defineFunction(String The namespace for the function or "" for no namesapce. prefix, String The name of the function. If empty (""), the method name is used as the function name. function, Method The `java.lang.reflect.Method` instance of the method that implements the function. method) Define an EL function in the local function mapper.
public Object	Returns: The result of the expression evaluation. eval(String The EL expression to be evaluated. expression) Evaluates an EL expression.
public ELManager	Returns: The ELManager used for EL processing. getELManager() Return the ELManager used for EL processing.
public Object	Returns: The result of the expression evaluation. getValue(String The EL expression to be evaluated. expression, Class<?> Specifies the type that the resultant evaluation will be coerced to. expectedType) Evaluates an EL expression, and coerces the result to the specified type.
public void	setValue(String The target expression expression, Object The new value to set. value) Sets an expression with a new value.
public void	setVariable(String The name of the variable. var, String The EL expression to be assigned to the variable. expression) Assign an EL expression to an EL variable.
private static Class<?>	toClass(String type, ClassLoader loader) Return the Class object associated with the class or interface with the given name.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

elManager	back to summary
private ELManager elManager

factory	back to summary
private ExpressionFactory factory

Constructor Detail

ELProcessor	back to summary
public ELProcessor()

Method Detail

bracket	back to summary
private String bracket(String expression)

defineBean back to summary

defineBean	back to summary
public void defineBean(String name, Object bean) Define a bean in a local bean repository, hiding other beans of the same name. Parameters name:String The name of the bean bean:Object The bean instance to be defined. If `null`, the name will be removed from the local bean repository.

public void defineBean(String name, Object bean)

Define a bean in a local bean repository, hiding other beans of the same name.

Parameters

name:String: The name of the bean
bean:Object: The bean instance to be defined. If null, the name will be removed from the local bean repository.

defineFunction	back to summary
public void defineFunction(String prefix, String function, String className, String method) throws ClassNotFoundException, NoSuchMethodException Define an EL function in the local function mapper. Parameters prefix:String The namespace for the function or "" for no namesapce. function:String The name of the function. If empty (""), the method name is used as the function name. className:String The full Java class name that implements the function. method:String The name (specified without parenthesis) or the signature (as in the Java Language Spec) of the static method that implements the function. If the name (e.g. "sum") is given, the first declared method in class that matches the name is selected. If the signature (e.g. "int sum(int, int)" ) is given, then the declared method with the signature is selected. Exceptions ClassNotFoundException: if the specified class does not exists. NoSuchMethodException: if the method (with or without the signature) is not a declared method of the class, or if the method signature is not valid, or if the method is not a static method. NullPointerException: if any of the arguments is null.

defineFunction

back to summary

public void defineFunction(String prefix, String function, String className, String method) throws ClassNotFoundException, NoSuchMethodException

Define an EL function in the local function mapper.

Parameters

prefix:String: The namespace for the function or "" for no namesapce.
function:String: The name of the function. If empty (""), the method name is used as the function name.
className:String: The full Java class name that implements the function.
method:String: The name (specified without parenthesis) or the signature (as in the Java Language Spec) of the static method that implements the function. If the name (e.g. "sum") is given, the first declared method in class that matches the name is selected. If the signature (e.g. "int sum(int, int)" ) is given, then the declared method with the signature is selected.

Exceptions

ClassNotFoundException:: if the specified class does not exists.
NoSuchMethodException:: if the method (with or without the signature) is not a declared method of the class, or if the method signature is not valid, or if the method is not a static method.
NullPointerException:: if any of the arguments is null.

defineFunction back to summary

defineFunction	back to summary
public void defineFunction(String prefix, String function, Method method) throws NoSuchMethodException Define an EL function in the local function mapper. Parameters prefix:String The namespace for the function or "" for no namesapce. function:String The name of the function. If empty (""), the method name is used as the function name. method:Method The `java.lang.reflect.Method` instance of the method that implements the function. Exceptions NoSuchMethodException: if the method is not a static method NullPointerException: if any of the arguments is null.

public void defineFunction(String prefix, String function, Method method) throws NoSuchMethodException

Define an EL function in the local function mapper.

Parameters

prefix:String: The namespace for the function or "" for no namesapce.
function:String: The name of the function. If empty (""), the method name is used as the function name.
method:Method: The java.lang.reflect.Method instance of the method that implements the function.

Exceptions

NoSuchMethodException:: if the method is not a static method
NullPointerException:: if any of the arguments is null.

eval	back to summary
public Object eval(String expression) Evaluates an EL expression. Parameters expression:String The EL expression to be evaluated. Returns:Object The result of the expression evaluation.

eval

back to summary

public Object eval(String expression)

Evaluates an EL expression.

Parameters

expression:String: The EL expression to be evaluated.

Returns:Object

The result of the expression evaluation.

getELManager	back to summary
public ELManager getELManager() Return the ELManager used for EL processing. Returns:ELManager The ELManager used for EL processing.

getELManager

back to summary

public ELManager getELManager()

Return the ELManager used for EL processing.

Returns:ELManager: The ELManager used for EL processing.

getValue	back to summary
public Object getValue(String expression, Class<?> expectedType) Evaluates an EL expression, and coerces the result to the specified type. Parameters expression:String The EL expression to be evaluated. expectedType:Class<?> Specifies the type that the resultant evaluation will be coerced to. Returns:Object The result of the expression evaluation.

getValue

back to summary

public Object getValue(String expression, Class<?> expectedType)

Evaluates an EL expression, and coerces the result to the specified type.

Parameters

expression:String: The EL expression to be evaluated.
expectedType:Class<?>: Specifies the type that the resultant evaluation will be coerced to.

Returns:Object

The result of the expression evaluation.

setValue	back to summary
public void setValue(String expression, Object value) Sets an expression with a new value. The target expression is evaluated, up to the last property resolution, and the resultant (base, property) pair is set to the provided value. Parameters expression:String The target expression value:Object The new value to set. Exceptions PropertyNotFoundException: if one of the property resolutions failed because a specified variable or property does not exist or is not readable. PropertyNotWritableException: if the final variable or property resolution failed because the specified variable or property is not writable. ELException: if an exception was thrown while attempting to set the property or variable. The thrown exception must be included as the cause property of this exception, if available.

setValue

back to summary

public void setValue(String expression, Object value)

Sets an expression with a new value. The target expression is evaluated, up to the last property resolution, and the resultant (base, property) pair is set to the provided value.

Parameters

expression:String: The target expression
value:Object: The new value to set.

Exceptions

PropertyNotFoundException:: if one of the property resolutions failed because a specified variable or property does not exist or is not readable.
PropertyNotWritableException:: if the final variable or property resolution failed because the specified variable or property is not writable.
ELException:: if an exception was thrown while attempting to set the property or variable. The thrown exception must be included as the cause property of this exception, if available.

setVariable back to summary

setVariable	back to summary
public void setVariable(String var, String expression) Assign an EL expression to an EL variable. The expression is parsed, but not evaluated, and the parsed expression is mapped to the EL variable in the local variable map. Any previously assigned expression to the same variable will be replaced. If the expression is `null`, the variable will be removed. Parameters var:String The name of the variable. expression:String The EL expression to be assigned to the variable.

public void setVariable(String var, String expression)

Assign an EL expression to an EL variable. The expression is parsed, but not evaluated, and the parsed expression is mapped to the EL variable in the local variable map. Any previously assigned expression to the same variable will be replaced. If the expression is null, the variable will be removed.

Parameters

var:String: The name of the variable.
expression:String: The EL expression to be assigned to the variable.

toClass	back to summary
private static Class<?> toClass(String type, ClassLoader loader) throws ClassNotFoundException Return the Class object associated with the class or interface with the given name.

public Class ELProcessor

Scope and Life Cycle

Automatic Bracketing of Expressions

Example

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail