com.opensymphony.xwork2.ognl

## Class OgnlUtil

- java.lang.Object
- - com.opensymphony.xwork2.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 and Description
    `OgnlUtil()` Deprecated. It is recommended to utilize the {@link OgnlUtil#OgnlUtil(com.opensymphony.xwork2.ognl.ExpressionCacheFactory, com.opensymphony.xwork2.ognl.BeanInfoCacheFactory) method instead.
    `OgnlUtil(ExpressionCacheFactory<String,Object> ognlExpressionCacheFactory, BeanInfoCacheFactory<Class<?>,BeanInfo> ognlBeanInfoCacheFactory)` Construct a new OgnlUtil instance for use with the framework, with optional cache factories for OGNL Expression and BeanInfo caches.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 classResolver)`
    `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.
    `Set<Class<?>>` | `getExcludedClasses()`
    `Set<Class<?>>` | `getExcludedPackageExemptClasses()`
    `Set<Pattern>` | `getExcludedPackageNamePatterns()`
    `Set<String>` | `getExcludedPackageNames()`
    `PropertyDescriptor[]` | `getPropertyDescriptors(Class<?> clazz)` Get's the java beans property descriptors for the given class.
    `PropertyDescriptor[]` | `getPropertyDescriptors(Object source)` Get's 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)`
    `boolean` | `isDisallowProxyMemberAccess()`
    `protected void` | `setAllowStaticFieldAccess(String allowStaticFieldAccess)`
    `protected void` | `setBeanInfoCacheMaxSize(String maxSize)`
    `protected void` | `setContainer(Container container)`
    `protected void` | `setDevMode(String mode)`
    `protected void` | `setDevModeExcludedClasses(String commaDelimitedClasses)`
    `void` | `setDevModeExcludedPackageExemptClasses(String commaDelimitedClasses)`
    `protected void` | `setDevModeExcludedPackageNamePatterns(String commaDelimitedPackagePatterns)`
    `protected void` | `setDevModeExcludedPackageNames(String commaDelimitedPackageNames)`
    `protected void` | `setDisallowProxyMemberAccess(String disallowProxyMemberAccess)`
    `protected void` | `setEnableEvalExpression(String evalExpression)`
    `protected void` | `setEnableExpressionCache(String cache)`
    `protected void` | `setExcludedClasses(String commaDelimitedClasses)`
    `void` | `setExcludedPackageExemptClasses(String commaDelimitedClasses)`
    `protected void` | `setExcludedPackageNamePatterns(String commaDelimitedPackagePatterns)`
    `protected void` | `setExcludedPackageNames(String commaDelimitedPackageNames)`
    `protected void` | `setExpressionCacheMaxSize(String maxSize)`
    `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() to handle type conversion for collection elements.
    `protected void` | `setXWorkConverter(XWorkConverter conv)`

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

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

- - ### Constructor Detail

    - #### OgnlUtil

          @Deprecated
          public OgnlUtil()

      Deprecated. It is recommended to utilize the {@link OgnlUtil#OgnlUtil(com.opensymphony.xwork2.ognl.ExpressionCacheFactory, com.opensymphony.xwork2.ognl.BeanInfoCacheFactory) method instead.
      Construct a new OgnlUtil instance for use with the framework

    - #### OgnlUtil

          public OgnlUtil(ExpressionCacheFactory<String,Object> ognlExpressionCacheFactory,
                          BeanInfoCacheFactory<Class<?>,BeanInfo> ognlBeanInfoCacheFactory)

      Construct a new OgnlUtil instance for use with the framework, with optional cache factories for OGNL Expression and BeanInfo caches. NOTE: Although the extension points are defined for the optional cache factories, developer-defined overrides do do not appear to function at this time (it always appears to instantiate the default factories). Construction injectors do not allow the optional flag, so the definitions must be defined.
      Parameters:
        `ognlExpressionCacheFactory` - factory for Expression cache instance. If null, it uses a default
        `ognlBeanInfoCacheFactory` - factory for BeanInfo cache instance. If null, it uses a default

  - ### Method Detail

    - #### setXWorkConverter

          protected void setXWorkConverter(XWorkConverter conv)

    - #### setDevMode

          protected void setDevMode(String mode)

    - #### setEnableExpressionCache

          protected void setEnableExpressionCache(String cache)

    - #### setExpressionCacheMaxSize

          protected void setExpressionCacheMaxSize(String maxSize)

    - #### setBeanInfoCacheMaxSize

          protected void setBeanInfoCacheMaxSize(String maxSize)

    - #### setEnableEvalExpression

          protected void setEnableEvalExpression(String evalExpression)

    - #### setExcludedClasses

          protected void setExcludedClasses(String commaDelimitedClasses)

    - #### setDevModeExcludedClasses

          protected void setDevModeExcludedClasses(String commaDelimitedClasses)

    - #### setExcludedPackageNamePatterns

          protected void setExcludedPackageNamePatterns(String commaDelimitedPackagePatterns)

    - #### setDevModeExcludedPackageNamePatterns

          protected void setDevModeExcludedPackageNamePatterns(String commaDelimitedPackagePatterns)

    - #### setExcludedPackageNames

          protected void setExcludedPackageNames(String commaDelimitedPackageNames)

    - #### setDevModeExcludedPackageNames

          protected void setDevModeExcludedPackageNames(String commaDelimitedPackageNames)

    - #### setExcludedPackageExemptClasses

          public void setExcludedPackageExemptClasses(String commaDelimitedClasses)

    - #### setDevModeExcludedPackageExemptClasses

          public void setDevModeExcludedPackageExemptClasses(String commaDelimitedClasses)

    - #### getExcludedClasses

          public Set<Class<?>> getExcludedClasses()

    - #### getExcludedPackageNamePatterns

          public Set<Pattern> getExcludedPackageNamePatterns()

    - #### getExcludedPackageNames

          public Set<String> getExcludedPackageNames()

    - #### getExcludedPackageExemptClasses

          public Set<Class<?>> getExcludedPackageExemptClasses()

    - #### setContainer

          protected void setContainer(Container container)

    - #### setAllowStaticFieldAccess

          protected void setAllowStaticFieldAccess(String allowStaticFieldAccess)

    - #### setDisallowProxyMemberAccess

          protected void setDisallowProxyMemberAccess(String disallowProxyMemberAccess)

    - #### applyExpressionMaxLength

          protected void applyExpressionMaxLength(String maxLength)

      Parameters:
        `maxLength` - Injects the Struts OGNL expression maximum length.

    - #### isDisallowProxyMemberAccess

          public boolean isDisallowProxyMemberAccess()

    - #### 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() to handle type conversion for collection elements. Ideally, this should be handled by OGNL directly.
      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

      Get's 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 classResolver)

Copyright © 2000–2023 Apache Software Foundation. All rights reserved.