Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.opensymphony.xwork2.util
Class XWorkConverter

    java.lang.Object
      ognl.DefaultTypeConverter
          com.opensymphony.xwork2.util.XWorkConverter

All Implemented Interfaces:
  ognl.TypeConverter

Direct Known Subclasses:
  AnnotationXWorkConverter

    public class XWorkConverter

extends ognl.DefaultTypeConverter

XWorkConverter is a singleton used by many of the WebWork's Ognl extention 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), WebWork'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 WebWork 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, WebWork 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 ognl.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 <ww:property value="post"/> 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 WebWork (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: 2006-11-17 13:38:31 +0100 (Fr, 17 Nov 2006) $ $Id: XWorkConverter.java 1214 2006-11-17 12:38:31Z rainerh $
Author:
  Pat Lightbody, Rainer Hermanns, Alexandru Popescu, tm_jee
See Also:
  `XWorkBasicConverter`

Field Summary
`static String` | `CONVERSION_COLLECTION_PREFIX`
`static String` | `CONVERSION_ERROR_PROPERTY_PREFIX`
`static String` | `CONVERSION_PROPERTY_FULLNAME`
`protected HashMap<String,ognl.TypeConverter>` | `defaultMappings` Record class and its type converter mapping.
`protected ognl.TypeConverter` | `defaultTypeConverter`
`private static XWorkConverter` | `instance`
`static String` | `LAST_BEAN_CLASS_ACCESSED`
`static String` | `LAST_BEAN_PROPERTY_ACCESSED`
`protected static Log` | `LOG`
`protected HashMap<Class,Map<String,Object>>` | `mappings` Target class conversion Mappings.
`protected HashSet<Class>` | `noMapping` Unavailable target class conversion mappings, serves as a simple cache.
`protected ObjectTypeDeterminer` | `objectTypeDeterminer`
`static String` | `REPORT_CONVERSION_ERRORS`
`protected HashSet<String>` | `unknownMappings` Record classes that doesn't have conversion mapping defined.

Constructor Summary
`protected` | `XWorkConverter()`

Method Summary
`private Object` | `acceptableErrorValue(Class toClass)` not used
`(package private) void` | `addConverterMapping(Map<String,Object> mapping, Class clazz)` Looks for converter mappings for the specified class and adds it to an existing map.
`static String` | `buildConverterFilename(Class clazz)`
`private 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.
`private Map<String,Object>` | `conditionalReload(Class clazz, Map<String,Object> oldValues)`
`Object` | `convertValue(Map map, Object o, Class aClass)`
`Object` | `convertValue(Map context, Object target, Member member, String property, Object value, Class toClass)` Convert value from one form to another.
`(package private) ognl.TypeConverter` | `createTypeConverter(String className)`
`private Object[]` | `getClassProperty(Map context)`
`static String` | `getConversionErrorMessage(String propertyName, ValueStack stack)`
`protected Object` | `getConverter(Class clazz, String property)`
`static XWorkConverter` | `getInstance()`
`ObjectTypeDeterminer` | `getObjectTypeDeterminer()`
`protected void` | `handleConversionException(Map context, String property, Object value, Object object)`
`void` | `loadConversionProperties(String propsName)`
`ognl.TypeConverter` | `lookup(Class clazz)` Looks for a TypeConverter in the default mappings.
`ognl.TypeConverter` | `lookup(String className)` Looks for a TypeConverter in the default mappings.
`(package private) ognl.TypeConverter` | `lookupSuper(Class clazz)` Recurses through a class' interfaces and class hierarchy looking for a TypeConverter in the default mapping that can handle the specified class.
`void` | `registerConverter(String className, ognl.TypeConverter converter)`
`void` | `registerConverterNotFound(String className)`
`static void` | `resetInstance()`
`void` | `setDefaultConverter(ognl.TypeConverter defaultTypeConverter)`
`static void` | `setInstance(XWorkConverter instance)`
`void` | `setObjectTypeDeterminer(ObjectTypeDeterminer determiner)`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### instance

    private static XWorkConverter instance

### LOG

    protected static final Log LOG

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

### mappings

    protected HashMap<Class,Map<String,Object>> mappings

  Target class conversion Mappings.

       Map>
        - Class -> convert to class
        - Map
          - String -> property name
                      eg. Element_property, property etc.
          - Object -> String to represent properties
                      eg. value part of
                          KeyProperty_property=id
                   -> TypeConverter to represent an Ognl TypeConverter
                      eg. value part of
                          property=foo.bar.MyConverter
                   -> Class to represent a class
                      eg. value part of
                          Element_property=foo.bar.MyObject

### noMapping

    protected HashSet<Class> noMapping

  Unavailable target class conversion mappings, serves as a simple cache.

### defaultMappings

    protected HashMap<String,ognl.TypeConverter> defaultMappings

  Record class and its type converter mapping.

       - String - classname as String
       - TypeConverter - instance of TypeConverter

### unknownMappings

    protected HashSet<String> unknownMappings

  Record classes that doesn't have conversion mapping defined.

       - String -> classname as String

### defaultTypeConverter

    protected ognl.TypeConverter defaultTypeConverter

### objectTypeDeterminer

    protected ObjectTypeDeterminer objectTypeDeterminer

Constructor Detail

### XWorkConverter

    protected XWorkConverter()

Method Detail

### getConversionErrorMessage

    public static String getConversionErrorMessage(String propertyName,
                                                   ValueStack stack)

### getInstance

    public static XWorkConverter getInstance()

### setInstance

    public static void setInstance(XWorkConverter instance)

### buildConverterFilename

    public static String buildConverterFilename(Class clazz)

### resetInstance

    public static void resetInstance()

### setDefaultConverter

    public void setDefaultConverter(ognl.TypeConverter defaultTypeConverter)

### convertValue

    public Object convertValue(Map map,
                               Object o,
                               Class aClass)

  Overrides:
    `convertValue` in class `ognl.DefaultTypeConverter`

### convertValue

    public Object convertValue(Map 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 `ognl.TypeConverter`
  Overrides:
    `convertValue` in class `ognl.DefaultTypeConverter`
  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 ognl.TypeConverter lookup(String className)

  Looks for a TypeConverter in the default mappings.

  Parameters:
    `className` - name of the class the TypeConverter must handle
  Returns:
    a TypeConverter to handle the specified class or null if none can be found

### lookup

    public ognl.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 context,
                                             String property,
                                             Object value,
                                             Object object)

### registerConverter

    public void registerConverter(String className,
                                  ognl.TypeConverter converter)

### registerConverterNotFound

    public void registerConverterNotFound(String className)

### getClassProperty

    private Object[] getClassProperty(Map context)

### acceptableErrorValue

    private Object acceptableErrorValue(Class toClass)

  not used

### addConverterMapping

    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

    private 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 hierarcy.

  Parameters:
    `clazz` - the class to look for converter mappings for
  Returns:
    the converter mappings
  Throws:
    `Exception`

### conditionalReload

    private Map<String,Object> conditionalReload(Class clazz,
                                                 Map<String,Object> oldValues)
                                          throws Exception

  Throws:
    `Exception`

### createTypeConverter

    ognl.TypeConverter createTypeConverter(String className)
                                     throws Exception

  Throws:
    `Exception`

### loadConversionProperties

    public void loadConversionProperties(String propsName)
                                  throws IOException

  Throws:
    `IOException`

### lookupSuper

    ognl.TypeConverter lookupSuper(Class clazz)

  Recurses through a class' interfaces and class hierarchy looking for a TypeConverter in the default mapping that can handle the specified class.

  Parameters:
    `clazz` - the class the TypeConverter must handle
  Returns:
    a TypeConverter to handle the specified class or null if none can be found

### getObjectTypeDeterminer

    public ObjectTypeDeterminer getObjectTypeDeterminer()

### setObjectTypeDeterminer

    public void setObjectTypeDeterminer(ObjectTypeDeterminer determiner)

  Parameters:
    `determiner` -

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000-2007 Apache Software Foundation. All Rights Reserved.