: Class ConverterBase

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

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

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