com.opensymphony.xwork2.conversion.impl
Class XWorkConverter

java.lang.Object
  extended by com.opensymphony.xwork2.conversion.impl.DefaultTypeConverter
      extended by com.opensymphony.xwork2.conversion.impl.XWorkConverter
All Implemented Interfaces:
TypeConverter
Direct Known Subclasses:
AnnotationXWorkConverter

public class XWorkConverter
extends DefaultTypeConverter

XWorkConverter is a singleton used by many of the Struts 2'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), 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: 2009-09-17 05:41:19 +0200 (Thu, 17 Sep 2009) $ $Id: XWorkConverter.java 2058 2009-09-17 03:41:19Z 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,TypeConverter> defaultMappings
          Record class and its type converter mapping.
private  TypeConverter defaultTypeConverter
           
static String LAST_BEAN_CLASS_ACCESSED
           
static String LAST_BEAN_PROPERTY_ACCESSED
           
protected static Logger LOG
           
protected  HashMap<Class,Map<String,Object>> mappings
          Target class conversion Mappings.
static String MESSAGE_INDEX_BRACKET_PATTERN
           
static String MESSAGE_INDEX_PATTERN
           
static Pattern messageIndexPattern
           
protected  HashSet<Class> noMapping
          Unavailable target class conversion mappings, serves as a simple cache.
private  ObjectFactory objectFactory
           
static String PERIOD
           
static String REPORT_CONVERSION_ERRORS
           
protected  HashSet<String> unknownMappings
          Record classes that doesn't have conversion mapping defined.
 
Fields inherited from interface com.opensymphony.xwork2.conversion.TypeConverter
NO_CONVERSION_POSSIBLE, TYPE_CONVERTER_CONTEXT_KEY
 
Constructor Summary
protected XWorkConverter()
           
 
Method Summary
protected  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)
           
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.
private  Map<String,Object> conditionalReload(Class clazz, Map<String,Object> oldValues)
           
 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.
(package private)  TypeConverter createTypeConverter(String className)
           
private  Object[] getClassProperty(Map<String,Object> context)
           
static String getConversionErrorMessage(String propertyName, ValueStack stack)
           
protected  Object getConverter(Class clazz, String property)
           
private static List<String> getIndexValues(String propertyName)
           
protected  void handleConversionException(Map<String,Object> context, String property, Object value, Object object)
           
 void loadConversionProperties(String propsName)
           
 void loadConversionProperties(String propsName, boolean require)
           
 TypeConverter lookup(Class clazz)
          Looks for a TypeConverter in the default mappings.
 TypeConverter lookup(String className)
          Looks for a TypeConverter in the default mappings.
(package private)  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, TypeConverter converter)
           
 void registerConverterNotFound(String className)
           
private static String removeAllIndexesInProperyName(String propertyName)
           
 void setDefaultTypeConverter(XWorkBasicConverter conv)
           
 void setObjectFactory(ObjectFactory factory)
           
 
Methods inherited from class com.opensymphony.xwork2.conversion.impl.DefaultTypeConverter
bigDecValue, bigIntValue, booleanValue, convertValue, doubleValue, enumValue, getTypeConverter, longValue, stringValue, stringValue
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LOG

protected static final Logger 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

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

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

private TypeConverter defaultTypeConverter

objectFactory

private ObjectFactory objectFactory
Constructor Detail

XWorkConverter

protected XWorkConverter()
Method Detail

setObjectFactory

public void setObjectFactory(ObjectFactory factory)

setDefaultTypeConverter

public void setDefaultTypeConverter(XWorkBasicConverter conv)

getConversionErrorMessage

public static String getConversionErrorMessage(String propertyName,
                                               ValueStack stack)

removeAllIndexesInProperyName

private static String removeAllIndexesInProperyName(String propertyName)

getIndexValues

private static List<String> getIndexValues(String propertyName)

buildConverterFilename

public static 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:

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

registerConverter

public void registerConverter(String className,
                              TypeConverter converter)

registerConverterNotFound

public void registerConverterNotFound(String className)

getClassProperty

private Object[] getClassProperty(Map<String,Object> context)

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

TypeConverter createTypeConverter(String className)
                            throws Exception
Throws:
Exception

loadConversionProperties

public void loadConversionProperties(String propsName)

loadConversionProperties

public void loadConversionProperties(String propsName,
                                     boolean require)

lookupSuper

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


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