com.opensymphony.xwork2.conversion.impl

## Class XWorkConverter

- java.lang.Object
- - com.opensymphony.xwork2.conversion.impl.DefaultTypeConverter
  - - com.opensymphony.xwork2.conversion.impl.XWorkConverter

- All Implemented Interfaces:
    TypeConverter

      public class XWorkConverter
      extends DefaultTypeConverter

  XWorkConverter is a singleton used by many of the Struts 2's Ognl extension points, such as InstantiatingNullHandler, XWorkListPropertyAccessor etc to do object conversion.

  Type conversion is great for situations where you need to turn a String in to a more complex object. Because the web is type-agnostic (everything is a string in HTTP), Struts 2's type conversion features are very useful. For instance, if you were prompting a user to enter in coordinates in the form of a string (such as "3, 22"), you could have Struts 2 do the conversion both from String to Point and from Point to String.

  Using this "point" example, if your action (or another compound object in which you are setting properties on) has a corresponding ClassName-conversion.properties file, Struts 2 will use the configured type converters for conversion to and from strings. So turning "3, 22" in to new Point(3, 22) is done by merely adding the following entry to ClassName-conversion.properties (Note that the PointConverter should impl the TypeConverter interface):

  point = com.acme.PointConverter

  Your type converter should be sure to check what class type it is being requested to convert. Because it is used for both to and from strings, you will need to split the conversion method in to two parts: one that turns Strings in to Points, and one that turns Points in to Strings.

  After this is done, you can now reference your point (using <s:property value="point"/> in JSP or ${point} in FreeMarker) and it will be printed as "3, 22" again. As such, if you submit this back to an action, it will be converted back to a Point once again.

  In some situations you may wish to apply a type converter globally. This can be done by editing the file xwork-conversion.properties in the root of your class path (typically WEB-INF/classes) and providing a property in the form of the class name of the object you wish to convert on the left hand side and the class name of the type converter on the right hand side. For example, providing a type converter for all Point objects would mean adding the following entry:

  com.acme.Point = com.acme.PointConverter

  Type conversion should not be used as a substitute for i18n. It is not recommended to use this feature to print out properly formatted dates. Rather, you should use the i18n features of Struts 2 (and consult the JavaDocs for JDK's MessageFormat object) to see how a properly formatted date should be displayed.

  Any error that occurs during type conversion may or may not wish to be reported. For example, reporting that the input "abc" could not be converted to a number might be important. On the other hand, reporting that an empty string, "", cannot be converted to a number might not be important - especially in a web environment where it is hard to distinguish between a user not entering a value vs. entering a blank value.

  By default, all conversion errors are reported using the generic i18n key xwork.default.invalid.fieldvalue, which you can override (the default text is Invalid field value for field "xxx", where xxx is the field name) in your global i18n resource bundle.

  However, sometimes you may wish to override this message on a per-field basis. You can do this by adding an i18n key associated with just your action (Action.properties) using the pattern invalid.fieldvalue.xxx, where xxx is the field name.

  It is important to know that none of these errors are actually reported directly. Rather, they are added to a map called conversionErrors in the ActionContext. There are several ways this map can then be accessed and the errors can be reported accordingly.

  Version:
    $Date$ $Id$
  Author:
    Pat Lightbody, Rainer Hermanns, Alexandru Popescu, tm_jee
  See Also:
    `XWorkBasicConverter`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `CONVERSION_COLLECTION_PREFIX`
    `static String` | `CONVERSION_ERROR_PROPERTY_PREFIX`
    `static String` | `CONVERSION_PROPERTY_FULLNAME`
    `static String` | `LAST_BEAN_CLASS_ACCESSED`
    `static String` | `LAST_BEAN_PROPERTY_ACCESSED`
    `static String` | `MESSAGE_INDEX_BRACKET_PATTERN`
    `static String` | `MESSAGE_INDEX_PATTERN`
    `static Pattern` | `messageIndexPattern`
    `static String` | `PERIOD`
    `static String` | `REPORT_CONVERSION_ERRORS`

    - ### Fields inherited from class com.opensymphony.xwork2.conversion.impl.DefaultTypeConverter

      `MILLISECOND_FORMAT`

    - ### Fields inherited from interface com.opensymphony.xwork2.conversion.TypeConverter

      `NO_CONVERSION_POSSIBLE, TYPE_CONVERTER_CONTEXT_KEY`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `XWorkConverter()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addConverterMapping(Map<String,Object> mapping, Class clazz)` Looks for converter mappings for the specified class and adds it to an existing map.
    `String` | `buildConverterFilename(Class clazz)`
    `protected Map<String,Object>` | `buildConverterMapping(Class clazz)` Looks for converter mappings for the specified class, traversing up its class hierarchy and interfaces and adding any additional mappings it may find.
    `Object` | `convertValue(Map<String,Object> map, Object o, Class aClass)`
    `Object` | `convertValue(Map<String,Object> context, Object target, Member member, String property, Object value, Class toClass)` Convert value from one form to another.
    `static String` | `getConversionErrorMessage(String propertyName, Class toClass, ValueStack stack)`
    `protected Object` | `getConverter(Class clazz, String property)`
    `protected void` | `handleConversionException(Map<String,Object> context, String property, Object value, Object object, Class toClass)`
    `TypeConverter` | `lookup(Class clazz)` Looks for a TypeConverter in the default mappings.
    `TypeConverter` | `lookup(String className, boolean isPrimitive)` Looks for a TypeConverter in the default mappings.
    `void` | `registerConverter(String className, TypeConverter converter)`
    `void` | `registerConverterNotFound(String className)`
    `void` | `setConversionAnnotationProcessor(ConversionAnnotationProcessor annotationProcessor)`
    `void` | `setConversionFileProcessor(ConversionFileProcessor fileProcessor)`
    `void` | `setDefaultTypeConverter(XWorkBasicConverter converter)`
    `void` | `setFileManagerFactory(FileManagerFactory fileManagerFactory)`
    `void` | `setReloadingConfigs(String reloadingConfigs)`
    `void` | `setTypeConverterHolder(TypeConverterHolder converterHolder)`

    - ### Methods inherited from class com.opensymphony.xwork2.conversion.impl.DefaultTypeConverter

      `bigDecValue, bigIntValue, booleanValue, convertValue, doubleValue, enumValue, getLocale, getTypeConverter, longValue, setContainer, stringValue, stringValue`

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

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

- - ### Field Detail

    - #### REPORT_CONVERSION_ERRORS

          public static final String REPORT_CONVERSION_ERRORS

      See Also:
        Constant Field Values

    - #### CONVERSION_PROPERTY_FULLNAME

          public static final String CONVERSION_PROPERTY_FULLNAME

      See Also:
        Constant Field Values

    - #### CONVERSION_ERROR_PROPERTY_PREFIX

          public static final String CONVERSION_ERROR_PROPERTY_PREFIX

      See Also:
        Constant Field Values

    - #### CONVERSION_COLLECTION_PREFIX

          public static final String CONVERSION_COLLECTION_PREFIX

      See Also:
        Constant Field Values

    - #### LAST_BEAN_CLASS_ACCESSED

          public static final String LAST_BEAN_CLASS_ACCESSED

      See Also:
        Constant Field Values

    - #### LAST_BEAN_PROPERTY_ACCESSED

          public static final String LAST_BEAN_PROPERTY_ACCESSED

      See Also:
        Constant Field Values

    - #### MESSAGE_INDEX_PATTERN

          public static final String MESSAGE_INDEX_PATTERN

      See Also:
        Constant Field Values

    - #### MESSAGE_INDEX_BRACKET_PATTERN

          public static final String MESSAGE_INDEX_BRACKET_PATTERN

      See Also:
        Constant Field Values

    - #### PERIOD

          public static final String PERIOD

      See Also:
        Constant Field Values

    - #### messageIndexPattern

          public static final Pattern messageIndexPattern

  - ### Constructor Detail

    - #### XWorkConverter

          protected XWorkConverter()

  - ### Method Detail

    - #### setDefaultTypeConverter

          public void setDefaultTypeConverter(XWorkBasicConverter converter)

    - #### setFileManagerFactory

          public void setFileManagerFactory(FileManagerFactory fileManagerFactory)

    - #### setReloadingConfigs

          public void setReloadingConfigs(String reloadingConfigs)

    - #### setConversionFileProcessor

          public void setConversionFileProcessor(ConversionFileProcessor fileProcessor)

    - #### setConversionAnnotationProcessor

          public void setConversionAnnotationProcessor(ConversionAnnotationProcessor annotationProcessor)

    - #### setTypeConverterHolder

          public void setTypeConverterHolder(TypeConverterHolder converterHolder)

    - #### getConversionErrorMessage

          public static String getConversionErrorMessage(String propertyName,
                                                         Class toClass,
                                                         ValueStack stack)

    - #### buildConverterFilename

          public String buildConverterFilename(Class clazz)

    - #### convertValue

          public Object convertValue(Map<String,Object> map,
                                     Object o,
                                     Class aClass)

      Overrides:
        `convertValue` in class `DefaultTypeConverter`

    - #### convertValue

          public Object convertValue(Map<String,Object> context,
                                     Object target,
                                     Member member,
                                     String property,
                                     Object value,
                                     Class toClass)

      Convert value from one form to another. Minimum requirement of arguments:
      - supplying context, toClass and value
      - supplying context, target and value.
      Specified by:
        `convertValue` in interface `TypeConverter`
      Overrides:
        `convertValue` in class `DefaultTypeConverter`
      Parameters:
        `context` - context under which the conversion is being done
        `target` - target object in which the property is being set
        `member` - member (Constructor, Method or Field) being set
        `property` - property name being set
        `value` - value to be converted
        `toClass` - type to which value is converted
      Returns:
        Converted value of type toType or TypeConverter.NoConversionPossible to indicate that the conversion was not possible.
      See Also:
        `TypeConverter.convertValue(java.util.Map, java.lang.Object, java.lang.reflect.Member, java.lang.String, java.lang.Object, java.lang.Class)`

    - #### lookup

          public TypeConverter lookup(String className,
                                      boolean isPrimitive)

      Looks for a TypeConverter in the default mappings.
      Parameters:
        `className` - name of the class the TypeConverter must handle
        `isPrimitive` - is primitive?
      Returns:
        a TypeConverter to handle the specified class or null if none can be found

    - #### lookup

          public TypeConverter lookup(Class clazz)

      Looks for a TypeConverter in the default mappings.
      Parameters:
        `clazz` - the class the TypeConverter must handle
      Returns:
        a TypeConverter to handle the specified class or null if none can be found

    - #### getConverter

          protected Object getConverter(Class clazz,
                                        String property)

    - #### handleConversionException

          protected void handleConversionException(Map<String,Object> context,
                                                   String property,
                                                   Object value,
                                                   Object object,
                                                   Class toClass)

    - #### registerConverter

          public void registerConverter(String className,
                                        TypeConverter converter)

    - #### registerConverterNotFound

          public void registerConverterNotFound(String className)

    - #### addConverterMapping

          protected void addConverterMapping(Map<String,Object> mapping,
                                             Class clazz)

      Looks for converter mappings for the specified class and adds it to an existing map. Only new converters are added. If a converter is defined on a key that already exists, the converter is ignored.
      Parameters:
        `mapping` - an existing map to add new converter mappings to
        `clazz` - class to look for converter mappings for

    - #### buildConverterMapping

          protected Map<String,Object> buildConverterMapping(Class clazz)
                                                      throws Exception

      Looks for converter mappings for the specified class, traversing up its class hierarchy and interfaces and adding any additional mappings it may find. Mappings lower in the hierarchy have priority over those higher in the hierarchy.
      Parameters:
        `clazz` - the class to look for converter mappings for
      Returns:
        the converter mappings
      Throws:
        `Exception` - in case of any errors

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