Package org.apache.commons.ognl

Class Ognl

java.lang.Object
org.apache.commons.ognl.Ognl
public abstract class Ognl extends Object

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 Details

    • Ognl

      private Ognl()
      You can't make one of these.

  • Method Details

    • parseExpression

      public static Object parseExpression(String expression) throws OgnlException
      Parses the given OGNL expression and returns a tree representation of the expression that can be used by Ognl static methods.
      Parameters:
      expression - the OGNL expression to be parsed
      Returns:
      a tree representation of the expression
      Throws:
      ExpressionSyntaxException - if the expression is malformed
      OgnlException - 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 the OgnlExpressionCompiler returned from OgnlRuntime.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 the ExpressionAccessor 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

      public static Map<String,Object> createDefaultContext(Object root)
      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 and context set appropriately

    • createDefaultContext

      public static Map<String,Object> createDefaultContext(Object root, ClassResolver classResolver)
      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 instantiate Class instances referenced in the expression.
      Returns:
      a new OgnlContext with the keys root and context 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 instantiate Class 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 and context 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 instantiate Class 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 and context set appropriately

    • addDefaultContext

      public static Map<String,Object> addDefaultContext(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.
      Parameters:
      root - the root of the object graph
      context - the context to which OGNL context will be added.
      Returns:
      Context Map with the keys root and context 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 instantiate Class instances referenced in the expression.
      context - The context to which OGNL context will be added.
      Returns:
      Context Map with the keys root and context 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 instantiate Class 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 and context 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 graph
      classResolver - 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 an OgnlContext will be dumped into a new OgnlContext object.
      Returns:
      Context Map with the keys root and context set appropriately

    • setClassResolver

      public static void setClassResolver(Map<String,Object> context, ClassResolver classResolver)
      Configures the ClassResolver 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

      public static ClassResolver getClassResolver(Map<String,Object> context)
      Gets the previously stored ClassResolver 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

      public static void setTypeConverter(Map<String,Object> context, TypeConverter converter)
      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

      public static TypeConverter getTypeConverter(Map<String,Object> context)
      Gets the currently configured TypeConverter for the given context - if any.
      Parameters:
      context - The context to get the converter from.
      Returns:
      The converter - or null if none found.

    • setMemberAccess

      public static void setMemberAccess(Map<String,Object> context, MemberAccess memberAccess)
      Configures the specified context with a MemberAccess instance for handling field/method protection levels.
      Parameters:
      context - The context to configure.
      memberAccess - The access resolver to configure the context with.

    • getMemberAccess

      public static MemberAccess getMemberAccess(Map<String,Object> context)
      Gets the currently stored MemberAccess 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

      public static void setRoot(Map<String,Object> context, Object root)
      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

      public static Object getRoot(Map<String,Object> context)
      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

      public static Evaluation getLastEvaluation(Map<String,Object> context)
      Gets the last Evaluation 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 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 via addDefaultContext().
      Parameters:
      tree - the OGNL expression tree to evaluate, as returned by parseExpression()
      context - the naming context for the evaluation
      root - the root object for the OGNL expression
      Returns:
      the result of evaluating the expression
      Throws:
      MethodFailedException - if the expression called a method which failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - 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 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 via addDefaultContext().
      Parameters:
      tree - the OGNL expression tree to evaluate, as returned by parseExpression()
      context - the naming context for the evaluation
      root - the root object for the OGNL expression
      resultType - 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 failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - if there is a pathological environmental problem

    • getValue

      public static <T> T getValue(ExpressionAccessor expression, OgnlContext context, Object root)
      Gets the value represented by the given pre-compiled expression on the specified root object.
      Parameters:
      expression - The pre-compiled expression, as found in Node.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 in Node.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 the getTypeConverter(java.util.Map) .
      Returns:
      The value.
      Throws:
      OgnlException

    • getValue

      public static <T> T getValue(String expression, Map<String,Object> context, Object root) 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 parsed
      context - the naming context for the evaluation
      root - the root object for the OGNL expression
      Returns:
      the result of evaluating the expression
      Throws:
      MethodFailedException - if the expression called a method which failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - 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 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 parsed
      context - the naming context for the evaluation
      root - the root object for the OGNL expression
      resultType - 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 failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - if there is a pathological environmental problem
      See Also:

    • getValue

      public static <T> T getValue(Object tree, Object root) throws OgnlException
      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 failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - if there is a pathological environmental problem

    • getValue

      public static <T> T getValue(Object tree, Object root, Class<T> resultType) throws OgnlException
      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
      resultType - 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 failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - if there is a pathological environmental problem

    • getValue

      public static <T> T getValue(String expression, Object root) throws OgnlException
      Convenience method that combines calls to parseExpression and getValue.
      Parameters:
      expression - the OGNL expression to be parsed
      root - the root object for the OGNL expression
      Returns:
      the result of evaluating the expression
      Throws:
      ExpressionSyntaxException - if the expression is malformed
      MethodFailedException - if the expression called a method which failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - 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 to parseExpression and getValue.
      Parameters:
      expression - the OGNL expression to be parsed
      root - the root object for the OGNL expression
      resultType - 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 malformed
      MethodFailedException - if the expression called a method which failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - 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 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 via addDefaultContext().
      Parameters:
      tree - the OGNL expression tree to evaluate, as returned by parseExpression()
      context - the naming context for the evaluation
      root - the root object for the OGNL expression
      value - the value to insert into the object graph
      Throws:
      MethodFailedException - if the expression called a method which failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - 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 in Node.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 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 parsed
      context - the naming context for the evaluation
      root - the root object for the OGNL expression
      value - the value to insert into the object graph
      Throws:
      MethodFailedException - if the expression called a method which failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - if there is a pathological environmental problem

    • setValue

      public static void setValue(Object tree, 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.
      Parameters:
      tree - the OGNL expression tree to evaluate, as returned by parseExpression()
      root - the root object for the OGNL expression
      value - the value to insert into the object graph
      Throws:
      MethodFailedException - if the expression called a method which failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - if there is a pathological environmental problem

    • setValue

      public static void setValue(String expression, Object root, Object value) throws OgnlException
      Convenience method that combines calls to parseExpression and setValue.
      Parameters:
      expression - the OGNL expression to be parsed
      root - the root object for the OGNL expression
      value - the value to insert into the object graph
      Throws:
      ExpressionSyntaxException - if the expression is malformed
      MethodFailedException - if the expression called a method which failed
      NoSuchPropertyException - if the expression referred to a nonexistent property
      InappropriateExpressionException - if the expression can't be used in this context
      OgnlException - if there is a pathological environmental problem
      See Also:

    • isConstant

      public static boolean isConstant(Object tree, Map<String,Object> context) throws OgnlException
      Checks if the specified Node instance represents a constant expression.
      Parameters:
      tree - The Node 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 OgnlException
      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

      public static boolean isConstant(Object tree) throws OgnlException
      Same as isConstant(Object, java.util.Map) - only the Map context is created for you.
      Parameters:
      tree - The Node to check.
      Returns:
      True if the node represents a constant expression - false otherwise.
      Throws:
      OgnlException - If an exception occurs.

    • isConstant

      public static boolean isConstant(String expression) throws OgnlException
      Same as isConstant(String, java.util.Map) - only the Map 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

      public static boolean isSimpleProperty(Object tree) throws OgnlException
      Throws:
      OgnlException

    • isSimpleProperty

      public static boolean isSimpleProperty(String expression) throws OgnlException
      Throws:
      OgnlException

    • isSimpleNavigationChain

      public static boolean isSimpleNavigationChain(Object tree, Map<String,Object> context) throws OgnlException
      Throws:
      OgnlException

    • isSimpleNavigationChain

      public static boolean isSimpleNavigationChain(String expression, Map<String,Object> context) throws OgnlException
      Throws:
      OgnlException

    • isSimpleNavigationChain

      public static boolean isSimpleNavigationChain(Object tree) throws OgnlException
      Throws:
      OgnlException

    • isSimpleNavigationChain

      public static boolean isSimpleNavigationChain(String expression) throws OgnlException
      Throws:
      OgnlException