Class Ognl
This class provides static methods for parsing and interpreting OGNL expressions.
The simplest use of the Ognl class is to get the value of an expression from an object, without extra context or pre-parsing.
import org.apache.commons.ognl.Ognl; import org.apache.commons.ognl.OgnlException; ... try { result = Ognl.getValue( expression, root ); } catch ( OgnlException ex ) { // Report error or recover }
This will parse the expression given and evaluate it against the root object given, returning the result. If there is
an error in the expression, such as the property is not found, the exception is encapsulated into an
OgnlException
.
Other more sophisticated uses of Ognl can pre-parse expressions. This provides two advantages: in the case of
user-supplied expressions it allows you to catch parse errors before evaluation and it allows you to cache parsed
expressions into an AST for better speed during repeated use. The pre-parsed expression is always returned as an
Object
to simplify use for programs that just wish to store the value for repeated use and do not care
that it is an AST. If it does care it can always safely cast the value to an AST
type.
The Ognl class also takes a context map as one of the parameters to the set and get methods. This allows you
to put your own variables into the available namespace for OGNL expressions. The default context contains only the
#root
and #context
keys, which are required to be present. The
addDefaultContext(Object, Map)
method will alter an existing Map
to put the defaults in.
Here is an example that shows how to extract the documentName
property out of the root object and append
a string with the current user name in parens:
private Map<String, Object> context = new HashMap<String, Object>(); ... public void setUserName( String value ) { context.put("userName", value); } ... try { // get value using our own custom context map result = Ognl.getValue( "documentName + \" (\" + ((#userName == null) ? \"<nobody>\" : #userName ) + \")\"", context, root ); } catch ( OgnlException ex ) { // Report error or recover }
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionaddDefaultContext
(Object root, Map<String, Object> context) Appends the standard naming context for evaluating an OGNL expression into the context given so that cached maps can be used as a context.addDefaultContext
(Object root, ClassResolver classResolver, Map<String, Object> context) Appends the standard naming context for evaluating an OGNL expression into the context given so that cached maps can be used as a context.addDefaultContext
(Object root, ClassResolver classResolver, TypeConverter converter, Map<String, Object> context) Appends the standard naming context for evaluating an OGNL expression into the context given so that cached maps can be used as a context.addDefaultContext
(Object root, ClassResolver classResolver, TypeConverter converter, MemberAccess memberAccess, Map<String, Object> context) Appends the standard naming context for evaluating an OGNL expression into the context given so that cached maps can be used as a context.static Node
compileExpression
(OgnlContext context, Object root, String expression) Parses and compiles the given expression using theOgnlExpressionCompiler
returned fromOgnlRuntime.getCompiler(OgnlContext)
.createDefaultContext
(Object root) Creates and returns a new standard naming context for evaluating an OGNL expression.createDefaultContext
(Object root, ClassResolver classResolver) Creates and returns a new standard naming context for evaluating an OGNL expression.createDefaultContext
(Object root, ClassResolver classResolver, TypeConverter converter) Creates and returns a new standard naming context for evaluating an OGNL expression.createDefaultContext
(Object root, ClassResolver classResolver, TypeConverter converter, MemberAccess memberAccess) Creates and returns a new standard naming context for evaluating an OGNL expression.static ClassResolver
getClassResolver
(Map<String, Object> context) Gets the previously storedClassResolver
for the given context - if any.static Evaluation
getLastEvaluation
(Map<String, Object> context) Gets the lastEvaluation
executed on the given context.static MemberAccess
getMemberAccess
(Map<String, Object> context) Gets the currently storedMemberAccess
object for the given context - if any.static Object
Gets the stored root object for the given context - if any.static TypeConverter
getTypeConverter
(Map<String, Object> context) Gets the currently configuredTypeConverter
for the given context - if any.static <T> T
Evaluates the given OGNL expression tree to extract a value from the given root object.static <T> T
Evaluates the given OGNL expression tree to extract a value from the given root object.static <T> T
Evaluates the given OGNL expression tree to extract a value from the given root object.static <T> T
Evaluates the given OGNL expression tree to extract a value from the given root object.static <T> T
Convenience method that combines calls toparseExpression
andgetValue
.static <T> T
Convenience method that combines calls toparseExpression
andgetValue
.static <T> T
Evaluates the given OGNL expression to extract a value from the given root object in a given contextstatic <T> T
Evaluates the given OGNL expression to extract a value from the given root object in a given contextstatic <T> T
getValue
(ExpressionAccessor expression, OgnlContext context, Object root) Gets the value represented by the given pre-compiled expression on the specified root object.static <T> T
getValue
(ExpressionAccessor expression, OgnlContext context, Object root, Class<T> resultType) Gets the value represented by the given pre-compiled expression on the specified root object.static boolean
isConstant
(Object tree) Same asisConstant(Object, java.util.Map)
- only theMap
context is created for you.static boolean
isConstant
(Object tree, Map<String, Object> context) Checks if the specifiedNode
instance represents a constant expression.static boolean
isConstant
(String expression) Same asisConstant(String, java.util.Map)
- only theMap
instance is created for you.static boolean
isConstant
(String expression, Map<String, Object> context) Checks if the specified expression represents a constant expression.static boolean
static boolean
isSimpleNavigationChain
(Object tree, Map<String, Object> context) static boolean
isSimpleNavigationChain
(String expression) static boolean
isSimpleNavigationChain
(String expression, Map<String, Object> context) static boolean
isSimpleProperty
(Object tree) static boolean
isSimpleProperty
(Object tree, Map<String, Object> context) static boolean
isSimpleProperty
(String expression) static boolean
isSimpleProperty
(String expression, Map<String, Object> context) static Object
parseExpression
(String expression) Parses the given OGNL expression and returns a tree representation of the expression that can be used byOgnl
static methods.static void
setClassResolver
(Map<String, Object> context, ClassResolver classResolver) Configures theClassResolver
to use for the given context.static void
setMemberAccess
(Map<String, Object> context, MemberAccess memberAccess) Configures the specified context with aMemberAccess
instance for handling field/method protection levels.static void
Sets the root object to use for all expressions in the given context - doesn't necessarily replace root object instances explicitly passed in to other expression resolving methods on this class.static void
setTypeConverter
(Map<String, Object> context, TypeConverter converter) Configures the type converter to use for a given context.static void
Evaluates the given OGNL expression tree to insert a value into the object graph rooted at the given root object.static void
Evaluates the given OGNL expression tree to insert a value into the object graph rooted at the given root object.static void
Convenience method that combines calls toparseExpression
andsetValue
.static void
Evaluates the given OGNL expression to insert a value into the object graph rooted at the given root object given the context.static void
setValue
(ExpressionAccessor expression, OgnlContext context, Object root, Object value) Sets the value given using the pre-compiled expression on the specified root object.
-
Constructor Details
-
Ognl
private Ognl()You can't make one of these.
-
-
Method Details
-
parseExpression
Parses the given OGNL expression and returns a tree representation of the expression that can be used byOgnl
static methods.- Parameters:
expression
- the OGNL expression to be parsed- Returns:
- a tree representation of the expression
- Throws:
ExpressionSyntaxException
- if the expression is malformedOgnlException
- if there is a pathological environmental problem
-
compileExpression
public static Node compileExpression(OgnlContext context, Object root, String expression) throws Exception Parses and compiles the given expression using theOgnlExpressionCompiler
returned fromOgnlRuntime.getCompiler(OgnlContext)
.- Parameters:
context
- The context to use.root
- The root object for the given expression.expression
- The expression to compile.- Returns:
- The node with a compiled accessor set on
Node.getAccessor()
if compilation was successfull. In instances where compilation wasn't possible because of a partially null expression theExpressionAccessor
instance may be null and the compilation of this expression still possible at some as yet indertermined point in the future. - Throws:
Exception
- If a compilation error occurs.
-
createDefaultContext
Creates and returns a new standard naming context for evaluating an OGNL expression.- Parameters:
root
- the root of the object graph- Returns:
- a new Map with the keys
root
andcontext
set appropriately
-
createDefaultContext
Creates and returns a new standard naming context for evaluating an OGNL expression.- Parameters:
root
- The root of the object graph.classResolver
- The resolver used to instantiateClass
instances referenced in the expression.- Returns:
- a new OgnlContext with the keys
root
andcontext
set appropriately
-
createDefaultContext
public static Map<String,Object> createDefaultContext(Object root, ClassResolver classResolver, TypeConverter converter) Creates and returns a new standard naming context for evaluating an OGNL expression.- Parameters:
root
- The root of the object graph.classResolver
- The resolver used to instantiateClass
instances referenced in the expression.converter
- Converter used to convert return types of an expression in to their desired types.- Returns:
- a new Map with the keys
root
andcontext
set appropriately
-
createDefaultContext
public static Map<String,Object> createDefaultContext(Object root, ClassResolver classResolver, TypeConverter converter, MemberAccess memberAccess) Creates and returns a new standard naming context for evaluating an OGNL expression.- Parameters:
root
- The root of the object graph.classResolver
- The resolver used to instantiateClass
instances referenced in the expression.converter
- Converter used to convert return types of an expression in to their desired types.memberAccess
- Java security handling object to determine semantics for accessing normally private/protected methods / fields.- Returns:
- a new Map with the keys
root
andcontext
set appropriately
-
addDefaultContext
Appends the standard naming context for evaluating an OGNL expression into the context given so that cached maps can be used as a context.- Parameters:
root
- the root of the object graphcontext
- the context to which OGNL context will be added.- Returns:
- Context Map with the keys
root
andcontext
set appropriately
-
addDefaultContext
public static Map<String,Object> addDefaultContext(Object root, ClassResolver classResolver, Map<String, Object> context) Appends the standard naming context for evaluating an OGNL expression into the context given so that cached maps can be used as a context.- Parameters:
root
- The root of the object graph.classResolver
- The resolver used to instantiateClass
instances referenced in the expression.context
- The context to which OGNL context will be added.- Returns:
- Context Map with the keys
root
andcontext
set appropriately
-
addDefaultContext
public static Map<String,Object> addDefaultContext(Object root, ClassResolver classResolver, TypeConverter converter, Map<String, Object> context) Appends the standard naming context for evaluating an OGNL expression into the context given so that cached maps can be used as a context.- Parameters:
root
- The root of the object graph.classResolver
- The resolver used to instantiateClass
instances referenced in the expression.converter
- Converter used to convert return types of an expression in to their desired types.context
- The context to which OGNL context will be added.- Returns:
- Context Map with the keys
root
andcontext
set appropriately
-
addDefaultContext
public static Map<String,Object> addDefaultContext(Object root, ClassResolver classResolver, TypeConverter converter, MemberAccess memberAccess, Map<String, Object> context) Appends the standard naming context for evaluating an OGNL expression into the context given so that cached maps can be used as a context.- Parameters:
root
- the root of the object graphclassResolver
- The class loading resolver that should be used to resolve class references.converter
- The type converter to be used by default.memberAccess
- Definition for handling private/protected access.context
- Default context to use, if not anOgnlContext
will be dumped into a newOgnlContext
object.- Returns:
- Context Map with the keys
root
andcontext
set appropriately
-
setClassResolver
Configures theClassResolver
to use for the given context. Will be used during expression parsing / execution to resolve class names.- Parameters:
context
- The context to place the resolver.classResolver
- The resolver to use to resolve classes.
-
getClassResolver
Gets the previously storedClassResolver
for the given context - if any.- Parameters:
context
- The context to get the configured resolver from.- Returns:
- The resolver instance, or null if none found.
-
setTypeConverter
Configures the type converter to use for a given context. This will be used to convert into / out of various java class types.- Parameters:
context
- The context to configure it for.converter
- The converter to use.
-
getTypeConverter
Gets the currently configuredTypeConverter
for the given context - if any.- Parameters:
context
- The context to get the converter from.- Returns:
- The converter - or null if none found.
-
setMemberAccess
Configures the specified context with aMemberAccess
instance for handling field/method protection levels.- Parameters:
context
- The context to configure.memberAccess
- The access resolver to configure the context with.
-
getMemberAccess
Gets the currently storedMemberAccess
object for the given context - if any.- Parameters:
context
- The context to get the object from.- Returns:
- The configured
MemberAccess
instance in the specified context - or null if none found.
-
setRoot
Sets the root object to use for all expressions in the given context - doesn't necessarily replace root object instances explicitly passed in to other expression resolving methods on this class.- Parameters:
context
- The context to store the root object in.root
- The root object.
-
getRoot
Gets the stored root object for the given context - if any.- Parameters:
context
- The context to get the root object from.- Returns:
- The root object - or null if none found.
-
getLastEvaluation
Gets the lastEvaluation
executed on the given context.- Parameters:
context
- The context to get the evaluation from.- Returns:
- The
Evaluation
- or null if none was found.
-
getValue
public static <T> T getValue(Object tree, Map<String, Object> context, Object root) throws OgnlExceptionEvaluates the given OGNL expression tree to extract a value from the given root object. The default context is set for the given context and root viaaddDefaultContext()
.- Parameters:
tree
- the OGNL expression tree to evaluate, as returned by parseExpression()context
- the naming context for the evaluationroot
- the root object for the OGNL expression- Returns:
- the result of evaluating the expression
- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem
-
getValue
public static <T> T getValue(Object tree, Map<String, Object> context, Object root, Class<T> resultType) throws OgnlExceptionEvaluates the given OGNL expression tree to extract a value from the given root object. The default context is set for the given context and root viaaddDefaultContext()
.- Parameters:
tree
- the OGNL expression tree to evaluate, as returned by parseExpression()context
- the naming context for the evaluationroot
- the root object for the OGNL expressionresultType
- the converted type of the resultant object, using the context's type converter- Returns:
- the result of evaluating the expression
- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem
-
getValue
Gets the value represented by the given pre-compiled expression on the specified root object.- Parameters:
expression
- The pre-compiled expression, as found inNode.getAccessor()
.context
- The ognl context.root
- The object to retrieve the expression value from.- Returns:
- The value.
-
getValue
public static <T> T getValue(ExpressionAccessor expression, OgnlContext context, Object root, Class<T> resultType) throws OgnlException Gets the value represented by the given pre-compiled expression on the specified root object.- Parameters:
expression
- The pre-compiled expression, as found inNode.getAccessor()
.context
- The ognl context.root
- The object to retrieve the expression value from.resultType
- The desired object type that the return value should be converted to using thegetTypeConverter(java.util.Map)
.- Returns:
- The value.
- Throws:
OgnlException
-
getValue
public static <T> T getValue(String expression, Map<String, Object> context, Object root) throws OgnlExceptionEvaluates the given OGNL expression to extract a value from the given root object in a given context- Parameters:
expression
- the OGNL expression to be parsedcontext
- the naming context for the evaluationroot
- the root object for the OGNL expression- Returns:
- the result of evaluating the expression
- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem- See Also:
-
getValue
public static <T> T getValue(String expression, Map<String, Object> context, Object root, Class<T> resultType) throws OgnlExceptionEvaluates the given OGNL expression to extract a value from the given root object in a given context- Parameters:
expression
- the OGNL expression to be parsedcontext
- the naming context for the evaluationroot
- the root object for the OGNL expressionresultType
- the converted type of the resultant object, using the context's type converter- Returns:
- the result of evaluating the expression
- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem- See Also:
-
getValue
Evaluates the given OGNL expression tree to extract a value from the given root object.- Parameters:
tree
- the OGNL expression tree to evaluate, as returned by parseExpression()root
- the root object for the OGNL expression- Returns:
- the result of evaluating the expression
- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem
-
getValue
Evaluates the given OGNL expression tree to extract a value from the given root object.- Parameters:
tree
- the OGNL expression tree to evaluate, as returned by parseExpression()root
- the root object for the OGNL expressionresultType
- the converted type of the resultant object, using the context's type converter- Returns:
- the result of evaluating the expression
- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem
-
getValue
Convenience method that combines calls toparseExpression
andgetValue
.- Parameters:
expression
- the OGNL expression to be parsedroot
- the root object for the OGNL expression- Returns:
- the result of evaluating the expression
- Throws:
ExpressionSyntaxException
- if the expression is malformedMethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem- See Also:
-
getValue
public static <T> T getValue(String expression, Object root, Class<T> resultType) throws OgnlException Convenience method that combines calls toparseExpression
andgetValue
.- Parameters:
expression
- the OGNL expression to be parsedroot
- the root object for the OGNL expressionresultType
- the converted type of the resultant object, using the context's type converter- Returns:
- the result of evaluating the expression
- Throws:
ExpressionSyntaxException
- if the expression is malformedMethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem- See Also:
-
setValue
public static void setValue(Object tree, Map<String, Object> context, Object root, Object value) throws OgnlExceptionEvaluates the given OGNL expression tree to insert a value into the object graph rooted at the given root object. The default context is set for the given context and root viaaddDefaultContext()
.- Parameters:
tree
- the OGNL expression tree to evaluate, as returned by parseExpression()context
- the naming context for the evaluationroot
- the root object for the OGNL expressionvalue
- the value to insert into the object graph- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem
-
setValue
public static void setValue(ExpressionAccessor expression, OgnlContext context, Object root, Object value) Sets the value given using the pre-compiled expression on the specified root object.- Parameters:
expression
- The pre-compiled expression, as found inNode.getAccessor()
.context
- The ognl context.root
- The object to set the expression value on.value
- The value to set.
-
setValue
public static void setValue(String expression, Map<String, Object> context, Object root, Object value) throws OgnlExceptionEvaluates the given OGNL expression to insert a value into the object graph rooted at the given root object given the context.- Parameters:
expression
- the OGNL expression to be parsedcontext
- the naming context for the evaluationroot
- the root object for the OGNL expressionvalue
- the value to insert into the object graph- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem
-
setValue
Evaluates the given OGNL expression tree to insert a value into the object graph rooted at the given root object.- Parameters:
tree
- the OGNL expression tree to evaluate, as returned by parseExpression()root
- the root object for the OGNL expressionvalue
- the value to insert into the object graph- Throws:
MethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem
-
setValue
Convenience method that combines calls toparseExpression
andsetValue
.- Parameters:
expression
- the OGNL expression to be parsedroot
- the root object for the OGNL expressionvalue
- the value to insert into the object graph- Throws:
ExpressionSyntaxException
- if the expression is malformedMethodFailedException
- if the expression called a method which failedNoSuchPropertyException
- if the expression referred to a nonexistent propertyInappropriateExpressionException
- if the expression can't be used in this contextOgnlException
- if there is a pathological environmental problem- See Also:
-
isConstant
Checks if the specifiedNode
instance represents a constant expression.- Parameters:
tree
- TheNode
to check.context
- The context to use.- Returns:
- True if the node is a constant - false otherwise.
- Throws:
OgnlException
- If an error occurs checking the expression.
-
isConstant
public static boolean isConstant(String expression, Map<String, Object> context) throws OgnlExceptionChecks if the specified expression represents a constant expression.- Parameters:
expression
- The expression to check.context
- The context to use.- Returns:
- True if the node is a constant - false otherwise.
- Throws:
OgnlException
- If an error occurs checking the expression.
-
isConstant
Same asisConstant(Object, java.util.Map)
- only theMap
context is created for you.- Parameters:
tree
- TheNode
to check.- Returns:
- True if the node represents a constant expression - false otherwise.
- Throws:
OgnlException
- If an exception occurs.
-
isConstant
Same asisConstant(String, java.util.Map)
- only theMap
instance is created for you.- Parameters:
expression
- The expression to check.- Returns:
- True if the expression represents a constant - false otherwise.
- Throws:
OgnlException
- If an exception occurs.
-
isSimpleProperty
public static boolean isSimpleProperty(Object tree, Map<String, Object> context) throws OgnlException- Throws:
OgnlException
-
isSimpleProperty
public static boolean isSimpleProperty(String expression, Map<String, Object> context) throws OgnlException- Throws:
OgnlException
-
isSimpleProperty
- Throws:
OgnlException
-
isSimpleProperty
- Throws:
OgnlException
-