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. since 6.0.0. Use {@link #OgnlUtil(ExpressionCacheFactory, BeanInfoCacheFactory, OgnlGuard) instead.
    `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

    All Methods Static Methods Instance Methods Concrete Methods Deprecated 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 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.
    `Set<String>` | `getExcludedClasses()` Deprecated. since 6.4.0, no replacement.
    `Set<String>` | `getExcludedPackageExemptClasses()` Deprecated. since 6.4.0, no replacement.
    `Set<Pattern>` | `getExcludedPackageNamePatterns()` Deprecated. since 6.4.0, no replacement.
    `Set<String>` | `getExcludedPackageNames()` Deprecated. since 6.4.0, no replacement.
    `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)`
    `boolean` | `isDisallowDefaultPackageAccess()` Deprecated. since 6.4.0, no replacement.
    `boolean` | `isDisallowProxyMemberAccess()` Deprecated. since 6.4.0, no replacement.
    `protected void` | `setAllowStaticFieldAccess(String allowStaticFieldAccess)` Deprecated. since 6.4.0, no replacement.
    `protected void` | `setBeanInfoCacheMaxSize(String maxSize)` Deprecated. since 6.4.0, changing maximum cache size after initialisation is not necessary.
    `protected void` | `setContainer(Container container)`
    `protected void` | `setDevMode(String mode)`
    `protected void` | `setDevModeExcludedClasses(String commaDelimitedClasses)` Deprecated. since 6.5.0, no replacement.
    `void` | `setDevModeExcludedPackageExemptClasses(String commaDelimitedClasses)` Deprecated. since 6.5.0, no replacement.
    `protected void` | `setDevModeExcludedPackageNamePatterns(String commaDelimitedPackagePatterns)` Deprecated. since 6.5.0, no replacement.
    `protected void` | `setDevModeExcludedPackageNames(String commaDelimitedPackageNames)` Deprecated. since 6.5.0, no replacement.
    `protected void` | `setDisallowDefaultPackageAccess(String disallowDefaultPackageAccess)` Deprecated. since 6.4.0, no replacement.
    `protected void` | `setDisallowProxyMemberAccess(String disallowProxyMemberAccess)` Deprecated. since 6.4.0, no replacement.
    `protected void` | `setEnableEvalExpression(String evalExpression)`
    `protected void` | `setEnableExpressionCache(String cache)`
    `protected void` | `setExcludedClasses(String commaDelimitedClasses)` Deprecated. since 6.4.0, no replacement.
    `void` | `setExcludedPackageExemptClasses(String commaDelimitedClasses)` Deprecated. since 6.4.0, no replacement.
    `protected void` | `setExcludedPackageNamePatterns(String commaDelimitedPackagePatterns)` Deprecated. since 6.4.0, no replacement.
    `protected void` | `setExcludedPackageNames(String commaDelimitedPackageNames)` Deprecated. since 6.4.0, no replacement.
    `protected void` | `setExpressionCacheMaxSize(String maxSize)` Deprecated. since 6.4.0, changing maximum cache size after initialisation is not necessary.
    `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 Detail

    - #### OgnlUtil

          @Deprecated
          public OgnlUtil()

      Deprecated. since 6.0.0. Use {@link #OgnlUtil(ExpressionCacheFactory, BeanInfoCacheFactory, OgnlGuard) instead.
      Construct a new OgnlUtil instance for use with the framework

    - #### 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 Detail

    - #### setXWorkConverter

          protected void setXWorkConverter(XWorkConverter conv)

    - #### setDevMode

          protected void setDevMode(String mode)

    - #### setEnableExpressionCache

          protected void setEnableExpressionCache(String cache)

    - #### setExpressionCacheMaxSize

          @Deprecated
          protected void setExpressionCacheMaxSize(String maxSize)

      Deprecated. since 6.4.0, changing maximum cache size after initialisation is not necessary.

    - #### setBeanInfoCacheMaxSize

          @Deprecated
          protected void setBeanInfoCacheMaxSize(String maxSize)

      Deprecated. since 6.4.0, changing maximum cache size after initialisation is not necessary.

    - #### setEnableEvalExpression

          protected void setEnableEvalExpression(String evalExpression)

    - #### setExcludedClasses

          @Deprecated
          protected void setExcludedClasses(String commaDelimitedClasses)

      Deprecated. since 6.4.0, no replacement.

    - #### setDevModeExcludedClasses

          @Deprecated
          protected void setDevModeExcludedClasses(String commaDelimitedClasses)

      Deprecated. since 6.5.0, no replacement.

    - #### setExcludedPackageNamePatterns

          @Deprecated
          protected void setExcludedPackageNamePatterns(String commaDelimitedPackagePatterns)

      Deprecated. since 6.4.0, no replacement.

    - #### setDevModeExcludedPackageNamePatterns

          @Deprecated
          protected void setDevModeExcludedPackageNamePatterns(String commaDelimitedPackagePatterns)

      Deprecated. since 6.5.0, no replacement.

    - #### setExcludedPackageNames

          @Deprecated
          protected void setExcludedPackageNames(String commaDelimitedPackageNames)

      Deprecated. since 6.4.0, no replacement.

    - #### setDevModeExcludedPackageNames

          @Deprecated
          protected void setDevModeExcludedPackageNames(String commaDelimitedPackageNames)

      Deprecated. since 6.5.0, no replacement.

    - #### setExcludedPackageExemptClasses

          @Deprecated
          public void setExcludedPackageExemptClasses(String commaDelimitedClasses)

      Deprecated. since 6.4.0, no replacement.

    - #### setDevModeExcludedPackageExemptClasses

          @Deprecated
          public void setDevModeExcludedPackageExemptClasses(String commaDelimitedClasses)

      Deprecated. since 6.5.0, no replacement.

    - #### getExcludedClasses

          @Deprecated
          public Set<String> getExcludedClasses()

      Deprecated. since 6.4.0, no replacement.

    - #### getExcludedPackageNamePatterns

          @Deprecated
          public Set<Pattern> getExcludedPackageNamePatterns()

      Deprecated. since 6.4.0, no replacement.

    - #### getExcludedPackageNames

          @Deprecated
          public Set<String> getExcludedPackageNames()

      Deprecated. since 6.4.0, no replacement.

    - #### getExcludedPackageExemptClasses

          @Deprecated
          public Set<String> getExcludedPackageExemptClasses()

      Deprecated. since 6.4.0, no replacement.

    - #### setContainer

          protected void setContainer(Container container)

    - #### setAllowStaticFieldAccess

          @Deprecated
          protected void setAllowStaticFieldAccess(String allowStaticFieldAccess)

      Deprecated. since 6.4.0, no replacement.

    - #### setDisallowProxyMemberAccess

          @Deprecated
          protected void setDisallowProxyMemberAccess(String disallowProxyMemberAccess)

      Deprecated. since 6.4.0, no replacement.

    - #### setDisallowDefaultPackageAccess

          @Deprecated
          protected void setDisallowDefaultPackageAccess(String disallowDefaultPackageAccess)

      Deprecated. since 6.4.0, no replacement.

    - #### applyExpressionMaxLength

          protected void applyExpressionMaxLength(String maxLength)

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

    - #### isDisallowProxyMemberAccess

          @Deprecated
          public boolean isDisallowProxyMemberAccess()

      Deprecated. since 6.4.0, no replacement.

    - #### isDisallowDefaultPackageAccess

          @Deprecated
          public boolean isDisallowDefaultPackageAccess()

      Deprecated. since 6.4.0, no replacement.

    - #### 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)

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