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 ognl.Ognl; import 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 context = new HashMap(); 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 }
- Version:
- 27 June 1999
- Author:
- Luke Blanshard (blanshlu@netscape.net), Drew Davidson (drew@ognl.org)
-
Method Summary
Modifier and TypeMethodDescriptionstatic Map
addDefaultContext
(Object root, Map 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 Map
addDefaultContext
(Object root, ClassResolver classResolver, Map 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 Map
addDefaultContext
(Object root, ClassResolver classResolver, TypeConverter converter, Map 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 Map
addDefaultContext
(Object root, ClassResolver classResolver, TypeConverter converter, MemberAccess memberAccess, Map 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()
.static Map
createDefaultContext
(Object root) Creates and returns a new standard naming context for evaluating an OGNL expression.static Map
createDefaultContext
(Object root, ClassResolver classResolver) Creates and returns a new standard naming context for evaluating an OGNL expression.static Map
createDefaultContext
(Object root, ClassResolver classResolver, TypeConverter converter) Creates and returns a new standard naming context for evaluating an OGNL expression.static Map
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 context) Gets the previously storedClassResolver
for the given context - if any.static Evaluation
getLastEvaluation
(Map context) Gets the lastEvaluation
executed on the given context.static MemberAccess
getMemberAccess
(Map 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 context) Gets the currently configuredTypeConverter
for the given context - if any.static Object
Evaluates the given OGNL expression tree to extract a value from the given root object.static Object
Evaluates the given OGNL expression tree to extract a value from the given root object.static Object
Evaluates the given OGNL expression tree to extract a value from the given root object.static Object
Evaluates the given OGNL expression tree to extract a value from the given root object.static Object
Convenience method that combines calls toparseExpression
andgetValue
.static Object
Convenience method that combines calls toparseExpression
andgetValue
.static Object
Evaluates the given OGNL expression to extract a value from the given root object in a given contextstatic Object
Evaluates the given OGNL expression to extract a value from the given root object in a given contextstatic Object
getValue
(ExpressionAccessor expression, OgnlContext context, Object root) Gets the value represented by the given pre-compiled expression on the specified root object.static Object
getValue
(ExpressionAccessor expression, OgnlContext context, Object root, Class 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 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 context) Checks if the specified expression represents a constant expression.static boolean
static boolean
isSimpleNavigationChain
(Object tree, Map context) static boolean
isSimpleNavigationChain
(String expression) static boolean
isSimpleNavigationChain
(String expression, Map context) static boolean
isSimpleProperty
(Object tree) static boolean
isSimpleProperty
(Object tree, Map context) static boolean
isSimpleProperty
(String expression) static boolean
isSimpleProperty
(String expression, Map 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 context, ClassResolver classResolver) Configures theClassResolver
to use for the given context.static void
setMemberAccess
(Map 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 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.
-
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()
.- 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 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 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
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 addDefaultContext(Object root, ClassResolver classResolver, TypeConverter converter, Map 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 addDefaultContext(Object root, ClassResolver classResolver, TypeConverter converter, MemberAccess memberAccess, Map 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
Evaluates 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 Object getValue(Object tree, Map context, Object root, Class resultType) throws OgnlException Evaluates 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 Object getValue(ExpressionAccessor expression, OgnlContext context, Object root, Class resultType) 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.
-
getValue
Evaluates 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 Object getValue(String expression, Map context, Object root, Class resultType) throws OgnlException Evaluates 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 Object getValue(String expression, Object root, Class 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 context, Object root, Object value) throws OgnlException Evaluates 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 context, Object root, Object value) throws OgnlException Evaluates 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 parsedroot
- the root object for the OGNL expressioncontext
- the naming context for the evaluationvalue
- 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
Checks 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
- Throws:
OgnlException
-
isSimpleProperty
- Throws:
OgnlException
-
isSimpleProperty
- Throws:
OgnlException
-
isSimpleProperty
- Throws:
OgnlException
-