com.mortbay.Util
Class ConverterBase

java.lang.Object
  |
  +--com.mortbay.Util.ConverterBase
Direct Known Subclasses:
ArrayConverter, ContainerIteratorTransformer, ConverterSet, ConverterSet.PrimitiveConverter, ObjectConverter, PropertyTreeConverter

public abstract class ConverterBase
extends java.lang.Object
implements Converter

Class to add support for Converter writers.

This class adds some support functions for Converters. It implements the Converter interface and instead provides the doConvert() function, that must be overridden. This class checks whether the object to be converted is null or already of the correct type and handles those cases.

The doConvert() function takes a boolean flag to indicate whether this is a safe conversion (has no error reporting) or an unsafe conversion (error reporting). If unsafe, then an error should be reported if the Converter handles the type to convert to but was unable to convert the value. Errors are reported by returning a ConvertFail exception. This is then thrown from the unsafeConvert() function. Note the implementor is expected to call the correct conversion function if the context is used.

Converters for more complicated types (Arrays, complex objects, etc) should report ConvertMultiFail exceptions and attempt to convert all the elements of the type they are converting to so all errors are reported at once.

Notes

Converters can operate under a different paradigm, I call tranformation. Transformers derive from this class also, but must call setTransformMode(true) in their constructors (and should only be placed in ConverterSets where setTransformMode(true) has been called). Transformers don't convert TO a type, but rather, look at the type they have to convert FROM and decide if they want to transform it. Since the mechanism is identical, I am using the Converter framework, but calling the relevant classes Transformers.

Version:
1.0 Thu Jun 8 2000
Author:
Matthew Watson (mattw)
See Also:
Converter

Constructor Summary
ConverterBase()
           
 
Method Summary
 java.lang.Object convert(java.lang.Object toConvert, java.lang.Class convertTo, Converter context)
          Try to convert a value.
protected abstract  java.lang.Object doConvert(java.lang.Object toConvert, java.lang.Class convertTo, Converter context, boolean safe)
          Convert an Object to another type.
 void setTransformMode(boolean on)
          Set this ConverterSet into Transform mode.
 java.lang.Object unsafeConvert(java.lang.Object toConvert, java.lang.Class convertTo, Converter context)
          Try to convert a value and report errors if conversion not totally successful.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ConverterBase

public ConverterBase()
Method Detail

convert

public java.lang.Object convert(java.lang.Object toConvert,
                                java.lang.Class convertTo,
                                Converter context)
Description copied from interface: Converter
Try to convert a value.
Specified by:
convert in interface Converter
Tags copied from interface: Converter
Parameters:
toConvert - Value to convert
convertTo - Type to convert to
context - The context within which the converter was called. If Converters use other Converters, this is passed as the outermost Converter so that recursive calls have access to all available Converters. Converter implementations should pass this if passed null.
Returns:
The converted value, or null if not possible

unsafeConvert

public java.lang.Object unsafeConvert(java.lang.Object toConvert,
                                      java.lang.Class convertTo,
                                      Converter context)
                               throws ConvertFail
Description copied from interface: Converter
Try to convert a value and report errors if conversion not totally successful.
Specified by:
unsafeConvert in interface Converter
Tags copied from interface: Converter
Parameters:
toConvert - Value to convert
convertTo - Type to convert to
context - The context within which the converter was called. If Converters use other Converters, this is passed as the outermost Converter so that recursive calls have access to all available Converters. Converter implementations should pass this if passed null.
Returns:
The converted value.
Throws:
ConvertFail - If the conversion is not totally successful.

setTransformMode

public void setTransformMode(boolean on)
Set this ConverterSet into Transform mode. In this mode, the type of the Object to be converted is paramount, rather than the type to be converted to. This must be set if transforming objects where the value of the parameter convertTo in the convert call is irrelevant, otherwise the ConverterSet performs certain optimisations that will cause Transformers not to function.
Parameters:
on -  

doConvert

protected abstract java.lang.Object doConvert(java.lang.Object toConvert,
                                              java.lang.Class convertTo,
                                              Converter context,
                                              boolean safe)
Convert an Object to another type.
Parameters:
toConvert - Value to convert
convertTo - Type to convert to
context - The context within which the converter was called. If Converters use other Converters, this is passed as the outermost Converter so that recursive calls have access to all available Converters. Converter implementations should pass this if passed null.
safe - If false, errors should be returned.
Returns:
null if this converter doesn't handle this type to convertTo, or a ConvertFail exception if there was an error and safe is false.