org.osgi.util.converter

## Interface ConverterBuilder

    @ProviderType
    public interface ConverterBuilder

A builder to create a new converter with modified behavior based on an existing converter. The modified behavior is specified by providing rules and/or conversion functions. If multiple rules match they will be visited in sequence of registration. If a rule's function returns `null` the next rule found will be visited. If none of the rules can handle the conversion, the original converter will be used to perform the conversion.

Author:
  $Id$

### Method Summary

All Methods Instance Methods Abstract Methods
`Converter` `build()` Build the specified converter.
`ConverterBuilder` `errorHandler(ConverterFunction func)` Register a custom error handler.
`ConverterBuilder` `rule(ConverterFunction func)` Register a catch-all rule, will be called of no other rule matches.
`ConverterBuilder` `rule(TargetRule rule)` Register a conversion rule for this converter.
`ConverterBuilder` `rule(Type type, ConverterFunction func)` Register a conversion rule for this converter.

### Method Detail

#### build

    Converter build()

Build the specified converter. Each time this method is called a new custom converter is produced based on the rules registered with the builder.

Returns:
  A new converter with the rules provided to the builder.

#### errorHandler

    ConverterBuilder errorHandler(ConverterFunction func)

Register a custom error handler. The custom error handler will be called when the conversion would otherwise throw an exception. The error handler can either throw a different exception or return a value to be used for the failed conversion.

Parameters:
  `func` - The function to be used to handle errors.
Returns:
  This converter builder for further building.

#### rule

    ConverterBuilder rule(Type type,
                          ConverterFunction func)

Register a conversion rule for this converter. Note that only the target type is specified, so the rule will be visited for every conversion to the target type.

Parameters:
  `type` - The type that this rule will produce.
  `func` - The function that will handle the conversion.
Returns:
  This converter builder for further building.

#### rule

    ConverterBuilder rule(TargetRule rule)

Register a conversion rule for this converter.

Parameters:
  `rule` - A rule implementation.
Returns:
  This converter builder for further building.

#### rule

    ConverterBuilder rule(ConverterFunction func)

Register a catch-all rule, will be called of no other rule matches.

Parameters:
  `func` - The function that will handle the conversion.
Returns:
  This converter builder for further building.