Package org.apache.struts2.ognl

# Class OgnlUtil

java.lang.Object
org.apache.struts2.ognl.OgnlUtil

public class OgnlUtil extends Object
Utility class that provides common access to the Ognl APIs for setting and getting properties from objects (usually Actions).

Author:
  Jason Carreira

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `OgnlUtil(ExpressionCacheFactory<String,Object> ognlExpressionCacheFactory, BeanInfoCacheFactory<Class<?>,BeanInfo> ognlBeanInfoCacheFactory, OgnlGuard ognlGuard)`
  Construct a new OgnlUtil instance for use with the framework, with optional cache factories for OGNL Expression and BeanInfo caches.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `applyExpressionMaxLength(String maxLength)`
  `int`
  `beanInfoCacheSize()`
  Check the size of the BeanInfo cache (current number of elements).
  `Object`
  `callMethod(String name, Map<String,Object> context, Object root)`
  `void`
  `clearBeanInfoCache()`
  Provide a mechanism to clear the BeanInfo cache.
  `void`
  `clearExpressionCache()`
  Provide a mechanism to clear the OGNL expression cache.
  `static void`
  `clearRuntimeCache()`
  Convenience mechanism to clear the OGNL Runtime Cache via OgnlUtil.
  `Object`
  `compile(String expression)`
  `Object`
  `compile(String expression, Map<String,Object> context)`
  `void`
  `copy(Object from, Object to, Map<String,Object> context)`
  Copies the properties in the object "from" and sets them in the object "to" using specified type converter, or `XWorkConverter` if none is specified.
  `void`
  `copy(Object from, Object to, Map<String,Object> context, Collection<String> exclusions, Collection<String> inclusions)`
  Copies the properties in the object "from" and sets them in the object "to" using specified type converter, or `XWorkConverter` if none is specified.
  `void`
  `copy(Object from, Object to, Map<String,Object> context, Collection<String> exclusions, Collection<String> inclusions, Class<?> editable)`
  Copies the properties in the object "from" and sets them in the object "to" only setting properties defined in the given "editable" class (or interface) using specified type converter, or `XWorkConverter` if none is specified.
  `protected Map<String,Object>`
  `createDefaultContext(Object root)`
  `protected Map<String,Object>`
  `createDefaultContext(Object root, ognl.ClassResolver resolver)`
  `int`
  `expressionCacheSize()`
  Check the size of the expression cache (current number of elements).
  `BeanInfo`
  `getBeanInfo(Class<?> clazz)`
  Get's the java bean info for the given source.
  `BeanInfo`
  `getBeanInfo(Object from)`
  Get's the java bean info for the given source object.
  `Map<String,Object>`
  `getBeanMap(Object source)`
  Creates a Map with read properties for the given source object.
  `PropertyDescriptor[]`
  `getPropertyDescriptors(Class<?> clazz)`
  Get's the java beans property descriptors for the given class.
  `PropertyDescriptor[]`
  `getPropertyDescriptors(Object source)`
  Gets the java beans property descriptors for the given source.
  `Object`
  `getRealTarget(String property, Map<String,Object> context, Object root)`
  Looks for the real target with the specified property given a root Object which may be a CompoundRoot.
  `Object`
  `getValue(String name, Map<String,Object> context, Object root)`
  `Object`
  `getValue(String name, Map<String,Object> context, Object root, Class<?> resultType)`
  `protected void`
  `setContainer(Container container)`
  `protected void`
  `setDevMode(String mode)`
  `protected void`
  `setEnableEvalExpression(String evalExpression)`
  `protected void`
  `setEnableExpressionCache(String cache)`
  `void`
  `setProperties(Map<String,?> properties, Object o)`
  Sets the properties on the object using the default context, defaulting to not throwing exceptions for problems setting the properties.
  `void`
  `setProperties(Map<String,?> properties, Object o, boolean throwPropertyExceptions)`
  Sets the properties on the object using the default context.
  `void`
  `setProperties(Map<String,?> props, Object o, Map<String,Object> context)`
  Sets the object's properties using the default type converter, defaulting to not throw exceptions for problems setting the properties.
  `void`
  `setProperties(Map<String,?> props, Object o, Map<String,Object> context, boolean throwPropertyExceptions)`
  Sets the object's properties using the default type converter.
  `void`
  `setProperty(String name, Object value, Object o, Map<String,Object> context)`
  Sets the named property to the supplied value on the Object, defaults to not throwing property exceptions.
  `void`
  `setProperty(String name, Object value, Object o, Map<String,Object> context, boolean throwPropertyExceptions)`
  Sets the named property to the supplied value on the Object.
  `void`
  `setValue(String name, Map<String,Object> context, Object root, Object value)`
  Wrapper around Ognl#setValue
  `protected void`
  `setXWorkConverter(XWorkConverter conv)`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### OgnlUtil

    public OgnlUtil(ExpressionCacheFactory<String,Object> ognlExpressionCacheFactory, BeanInfoCacheFactory<Class<?>,BeanInfo> ognlBeanInfoCacheFactory, OgnlGuard ognlGuard)
    Construct a new OgnlUtil instance for use with the framework, with optional cache factories for OGNL Expression and BeanInfo caches.
    Parameters:
      `ognlExpressionCacheFactory` - factory for Expression cache instance
      `ognlBeanInfoCacheFactory` - factory for BeanInfo cache instance
      `ognlGuard` - OGNL Guard instance

- ## Method Details

  - ### setXWorkConverter

    protected void setXWorkConverter(XWorkConverter conv)

  - ### setDevMode

    protected void setDevMode(String mode)

  - ### setEnableExpressionCache

    protected void setEnableExpressionCache(String cache)

  - ### setEnableEvalExpression

    protected void setEnableEvalExpression(String evalExpression)

  - ### setContainer

    protected void setContainer(Container container)

  - ### applyExpressionMaxLength

    protected void applyExpressionMaxLength(String maxLength)
    Parameters:
      `maxLength` - Injects the Struts OGNL expression maximum length.

  - ### clearRuntimeCache

    public static void clearRuntimeCache()
    Convenience mechanism to clear the OGNL Runtime Cache via OgnlUtil. May be utilized by applications that generate many unique OGNL expressions over time. Note: This call affects the global OGNL cache, see (`OgnlRuntime.clearCache()` for details. Warning: Frequent calling if this method may negatively impact performance, but may be required to avoid memory exhaustion (resource leak) with too many OGNL expressions being cached.
    Since:
      2.5.21

  - ### clearExpressionCache

    public void clearExpressionCache()
    Provide a mechanism to clear the OGNL expression cache. May be utilized by applications that generate many unique OGNL expressions over time. Note: This call affects the current OgnlUtil instance. For Struts this is often a Singleton instance so it can be "effectively global". Warning: Frequent calling if this method may negatively impact performance, but may be required to avoid memory exhaustion (resource leak) with too many OGNL expressions being cached.
    Since:
      2.5.21

  - ### expressionCacheSize

    public int expressionCacheSize()
    Check the size of the expression cache (current number of elements).
    Returns:
      current number of elements in the expression cache.
    Since:
      2.5.21

  - ### clearBeanInfoCache

    public void clearBeanInfoCache()
    Provide a mechanism to clear the BeanInfo cache. May be utilized by applications that request BeanInfo and/or PropertyDescriptors for many unique classes or objects over time (especially dynamic objects). Note: This call affects the current OgnlUtil instance. For Struts this is often a Singleton instance so it can be "effectively global". Warning: Frequent calling if this method may negatively impact performance, but may be required to avoid memory exhaustion (resource leak) with too many BeanInfo elements being cached.
    Since:
      2.5.21

  - ### beanInfoCacheSize

    public int beanInfoCacheSize()
    Check the size of the BeanInfo cache (current number of elements).
    Returns:
      current number of elements in the BeanInfo cache.
    Since:
      2.5.21

  - ### setProperties

    public void setProperties(Map<String,?> props, Object o, Map<String,Object> context)
    Sets the object's properties using the default type converter, defaulting to not throw exceptions for problems setting the properties.
    Parameters:
      `props` - the properties being set
      `o` - the object
      `context` - the action context

  - ### setProperties

    public void setProperties(Map<String,?> props, Object o, Map<String,Object> context, boolean throwPropertyExceptions) throws ReflectionException
    Sets the object's properties using the default type converter.
    Parameters:
      `props` - the properties being set
      `o` - the object
      `context` - the action context
      `throwPropertyExceptions` - boolean which tells whether it should throw exceptions for problems setting the properties
    Throws:
      `ReflectionException`

  - ### setProperties

    public void setProperties(Map<String,?> properties, Object o)
    Sets the properties on the object using the default context, defaulting to not throwing exceptions for problems setting the properties.
    Parameters:
      `properties` - map of properties
      `o` - object

  - ### setProperties

    public void setProperties(Map<String,?> properties, Object o, boolean throwPropertyExceptions)
    Sets the properties on the object using the default context.
    Parameters:
      `properties` - the property map to set on the object
      `o` - the object to set the properties into
      `throwPropertyExceptions` - boolean which tells whether it should throw exceptions for problems setting the properties

  - ### setProperty

    public void setProperty(String name, Object value, Object o, Map<String,Object> context)
    Sets the named property to the supplied value on the Object, defaults to not throwing property exceptions.
    Parameters:
      `name` - the name of the property to be set
      `value` - the value to set into the named property
      `o` - the object upon which to set the property
      `context` - the context which may include the TypeConverter

  - ### setProperty

    public void setProperty(String name, Object value, Object o, Map<String,Object> context, boolean throwPropertyExceptions)
    Sets the named property to the supplied value on the Object.
    Parameters:
      `name` - the name of the property to be set
      `value` - the value to set into the named property
      `o` - the object upon which to set the property
      `context` - the context which may include the TypeConverter
      `throwPropertyExceptions` - boolean which tells whether it should throw exceptions for problems setting the property

  - ### getRealTarget

    public Object getRealTarget(String property, Map<String,Object> context, Object root) throws ognl.OgnlException
    Looks for the real target with the specified property given a root Object which may be a CompoundRoot.
    Parameters:
      `property` - the property
      `context` - context map
      `root` - compound root
    Returns:
      the real target or null if no object can be found with the specified property
    Throws:
      `ognl.OgnlException` - in case of ognl errors

  - ### setValue

    public void setValue(String name, Map<String,Object> context, Object root, Object value) throws ognl.OgnlException
    Wrapper around Ognl#setValue
    Parameters:
      `name` - the name
      `context` - context map
      `root` - root
      `value` - value
    Throws:
      `ognl.OgnlException` - in case of ognl errors

  - ### getValue

    public Object getValue(String name, Map<String,Object> context, Object root) throws ognl.OgnlException
    Throws:
      `ognl.OgnlException`

  - ### callMethod

    public Object callMethod(String name, Map<String,Object> context, Object root) throws ognl.OgnlException
    Throws:
      `ognl.OgnlException`

  - ### getValue

    public Object getValue(String name, Map<String,Object> context, Object root, Class<?> resultType) throws ognl.OgnlException
    Throws:
      `ognl.OgnlException`

  - ### compile

    public Object compile(String expression) throws ognl.OgnlException
    Throws:
      `ognl.OgnlException`

  - ### compile

    public Object compile(String expression, Map<String,Object> context) throws ognl.OgnlException
    Throws:
      `ognl.OgnlException`

  - ### copy

    public void copy(Object from, Object to, Map<String,Object> context, Collection<String> exclusions, Collection<String> inclusions)
    Copies the properties in the object "from" and sets them in the object "to" using specified type converter, or `XWorkConverter` if none is specified.
    Parameters:
      `from` - the source object
      `to` - the target object
      `context` - the action context we're running under
      `exclusions` - collection of method names to excluded from copying ( can be null)
      `inclusions` - collection of method names to included copying (can be null) note if exclusions AND inclusions are supplied and not null nothing will get copied.

  - ### copy

    public void copy(Object from, Object to, Map<String,Object> context, Collection<String> exclusions, Collection<String> inclusions, Class<?> editable)
    Copies the properties in the object "from" and sets them in the object "to" only setting properties defined in the given "editable" class (or interface) using specified type converter, or `XWorkConverter` if none is specified.
    Parameters:
      `from` - the source object
      `to` - the target object
      `context` - the action context we're running under
      `exclusions` - collection of method names to excluded from copying ( can be null)
      `inclusions` - collection of method names to included copying (can be null) note if exclusions AND inclusions are supplied and not null nothing will get copied.
      `editable` - the class (or interface) to restrict property setting to

  - ### copy

    public void copy(Object from, Object to, Map<String,Object> context)
    Copies the properties in the object "from" and sets them in the object "to" using specified type converter, or `XWorkConverter` if none is specified.
    Parameters:
      `from` - the source object
      `to` - the target object
      `context` - the action context we're running under

  - ### getPropertyDescriptors

    public PropertyDescriptor[] getPropertyDescriptors(Object source) throws IntrospectionException
    Gets the java beans property descriptors for the given source.
    Parameters:
      `source` - the source object.
    Returns:
      property descriptors.
    Throws:
      `IntrospectionException` - is thrown if an exception occurs during introspection.

  - ### getPropertyDescriptors

    public PropertyDescriptor[] getPropertyDescriptors(Class<?> clazz) throws IntrospectionException
    Get's the java beans property descriptors for the given class.
    Parameters:
      `clazz` - the source object.
    Returns:
      property descriptors.
    Throws:
      `IntrospectionException` - is thrown if an exception occurs during introspection.

  - ### getBeanMap

    public Map<String,Object> getBeanMap(Object source) throws IntrospectionException, ognl.OgnlException
    Creates a Map with read properties for the given source object.

    If the source object does not have a read property (i.e. write-only) then the property is added to the map with the value `here is no read method for property-name`.

    Parameters:
      `source` - the source object.
    Returns:
      a Map with (key = read property name, value = value of read property).
    Throws:
      `IntrospectionException` - is thrown if an exception occurs during introspection.
      `ognl.OgnlException` - is thrown by OGNL if the property value could not be retrieved

  - ### getBeanInfo

    public BeanInfo getBeanInfo(Object from) throws IntrospectionException
    Get's the java bean info for the given source object. Calls getBeanInfo(Class c).
    Parameters:
      `from` - the source object.
    Returns:
      java bean info.
    Throws:
      `IntrospectionException` - is thrown if an exception occurs during introspection.

  - ### getBeanInfo

    public BeanInfo getBeanInfo(Class<?> clazz) throws IntrospectionException
    Get's the java bean info for the given source.
    Parameters:
      `clazz` - the source class.
    Returns:
      java bean info.
    Throws:
      `IntrospectionException` - is thrown if an exception occurs during introspection.

  - ### createDefaultContext

    protected Map<String,Object> createDefaultContext(Object root)

  - ### createDefaultContext

    protected Map<String,Object> createDefaultContext(Object root, ognl.ClassResolver resolver)