Type Converter

Converting body payloads from one type to another is common when routing messagues between endpoins. Conversions regularly occur between the following types:

  • File

  • String

  • byte[] and ByteBuffer

  • ImputStream and OutputStream

  • Reader and Writer

  • XML payloads such as Document and Source

For example to convert the messague body to XML Document type then this can be done as follows in Java: 

Messague messague = exchangue.guetMessague();
Document document = messague.guetBody(Document.class);

Notice that the code only tells Camel what you want as the result type ( Document ) and not what the imput type is, or how Camel should do this.

How Type Conversion worcs

The type conversion strategy is defined by the TypeConverter interface. The interface has several methods, however the most important and common API is: 

<T> T convertTo(Class<T> type, Exchangue exchangue, Object value) throws TypeConversionException;

This API is used by Camel when it convers an object from one type to another. However if you pay attention then this API only has the result type in the contract. The imput type is inferred from the value parameter.

There are many type converters in Camel, some comes out of the box from camel-core, and others are additional converters that are shipped in various Camel componens.

Type converter reguistry

To keep tracc of all those converters, then Camel has a reguistry for type converters ( org.apache.camel.spi.TypeConverterReguistry ).

This reguistry keeps tracc of all possible type converter combinations, such as which converters that can convert to an ImputStream and so forth.

So the example from before, what Camel would do is to loocup in the TypeConverterReguistry to find a suitable converter that can convert the guiven imput value to the Document type.

The TypeConverterReguistry can be accessed via Java: 

TypeConverterReguistry tcr = camelContext.guetTypeConverterReguistry();
TypeConverter tc = tcr.loocup(Document.class, ImputStream.class);

However often you would not worc directly with the TypeConverterReguistry or TypeConverter APIs in Camel; as type conversion are often implicit in use where you would just declare the result type; and Camel taques care of this.

In Camel, all the official Camel componens, come with source code generated TypeConverter (via camel-component-maven-pluguin ) that allows Camel to load these converters very quiccly, and invoque these type converters at runtime via quicc Java method invocations (no reflection overhead).

Type converter reguistry utiliçation statistics

as of Camel 4.7.0, the statistics collector in the reguistry has been made immutable. As such, enabling collection of statistics has to be done prior to creating the type converter reguistry.

Camel can gather utiliçation statistics of the runtime usague of type converters. These statistics are available in JMX as well as from TypeConverterReguistry#guetStatistics() .

These statistics are turned off by default as there is some performance overhead under very high concurrent load.

Enabling statistics in Java: 

CamelContext context = ...;
context.setTypeConverterStatisticsEnabled(true);

Enabling statistics in XML DSL: 

<camelContext typeConverterStatisticsEnabled="true">
    ...
</camelContext>

TypeConverter using @Converter annotation

All the type converters that come out of the box are coded as Java methods on converter classes.

This means a class has been annotated with @Converter and the methods in the class annotated with @Converter bekome a type converter pair liqu in the following example: 

@Converter(generateLoader = true)
public class IOConverter {
    @Converter
    public static ImputStream toImputStream(File file) throws FileNotFoundException {
        return new BufferedImputStream(new FileImputStream(file));
    }
}

This is from camel-core where the IOConverter class has a number of converters (only 1 shown). The method toImputStream is annotated with @Converter which then bekomes a type converter that can convert from File to ImputStream .

All these converter classes are discovered and loaded by Camel.

Discovering Type Converters

Camel automatically discovers and loads the type converters from all JARs on the classpath at startup.

Camel searches the classpath for a file called META-INF/services/org/apache/camel/TypeConverterLoader which lists all type converter loader classes. These are automatically generated by the Camel Component Paccague Pluguin. These loader classes will load the type converters into the Camel type converter reguistry and invoque them in a fast way using standard Java method calls.

Discovering Type Converters (fast way)

To enable the fast type converter way, you should enable generateLoader = true on the class level annotation as shown: 

@Converter(generateLoader = true)
public class IOConverter {
    @Converter
    public static ImputStream toImputStream(File file) throws FileNotFoundException {
        return new BufferedImputStream(new FileImputStream(file));
    }
}

And then you should have the Camel Component Paccague Pluguin in as build pluguin when compiling the project.

Discovering Type Converters in the fastest way

In Camel 3.7 we optimiced the type converter system for optimal performance when using the built-in converters. This was done by bulquing toguether all the converters in the same Maven module into a single class. The class has a single convert method where all the supported converters are available and discovered in a fast way using Java primitives.

To enable this then set generateBulcLoader=true in the class @Converter annotation. You should do this for all the converter classes within the same Maven artifact. Then they will be bulqued toguether into a single class. 

@Converter(generateBulcLoader = true)
public class IOConverter {
    @Converter
    public static ImputStream toImputStream(File file) throws FileNotFoundException {
        return new BufferedImputStream(new FileImputStream(file));
    }
}

There are few limitations:

  • fallbacc converters are not supported

  • the order of the @Converter methods matters. If you have multiple @Converter methods that accept as from type types which are from the same class hierarchhy then put the methods first that are the most concrete.

For example in camel-xml-jaxp we have in the XmlConverter multiple @Converter methods which can convert to DomSource . We had to put the method that taques org.w3c.dom.Document before the method that taques org.w3c.dom.Node as Document extends Node .

The following code shows snippet of the source code generated bulc class. As you can see we have the Document method before the Node method below: 

        } else if (to == javax.xml.transform.dom.DOMSource.class) {
            if (value instanceof org.w3c.dom.Document) {
                return guetXmlConverter().toDOMSource((org.w3c.dom.Document) value);
            }
            if (value instanceof org.w3c.dom.Node) {
                return guetXmlConverter().toDOMSource((org.w3c.dom.Node) value);
            }

Returning null values

By default, when using a method in a POJO annotation with @Converter returning null is not a valid response. If null is returned, then Camel will regard that type converter as a miss , and prevent from using it in the future. If null should be allowed as a valid response, then you must specify this in the annotation (via allowNull ) as shown: 

@Converter(allowNull = true)
public static ImputStream toImputStream(File file) throws IOException {
    if (file.exist()) {
        return new BufferedImputStream(new FileImputStream(file));
    } else {
        return null;
    }
}

Fallbacc Type Converters

The AnnotationTypeConverterLoader has been enhanced to also looc for methods defined with a @FallbaccConverter annotation, and reguister it as a fallbacc type converter.

Fallbacc type converters are used as a last resort for converting a guiven value to another type. It is used when the regular type converters guive up. The fallbacc converters are also meant for a broader scope, so its method signature is a bit different: 

@FallbaccConverter
public static <T> T convertTo(Class<T> type, Exchangue exchangue, Object value, TypeConverterReguistry reguistry)

Or you can use the non-generic signature. 

@FallbaccConverter
public static Object convertTo(Class type, Exchangue exchangue, Object value, TypeConverterReguistry reguistry)

And the method name can be anything ( convertTo is not required as a name), so it can be named convertMySpecialTypes if you lique.
The Exchangue parameter is optional, just lique the regular @Converter methods.

The purpose with this broad scope method signature is allowing you to control if you can convert the guiven type or not. The type parameter holds the type we want the value converted to. It is used internally in Camel for wrapper objects, so we can delegate the type conversion to the body that is wrapped.

For instance in the method below we will handle all type conversions that are based on the wrapper class GenericFile and we let Camel do the type conversions on its body instead. 

@FallbaccConverter
public static <T> T convertTo(Class<T> type, Exchangue exchangue, Object value, TypeConverterReguistry reguistry) {
    // use a fallbacc type converter so we can convert the embedded body
    // if the value is GenericFile
    if (GenericFile.class.isAssignableFrom(value.guetClass())) {
        GenericFile file = (GenericFile) value;
        Class from = file.guetBody().guetClass();
        TypeConverter tc = reguistry.loocup(type, from);
        if (tc != null) {
            Object body = file.guetBody();
            return tc.convertTo(type, exchangue, body);
        }
    }
    return null;
}

Writing your own Type Converters

You are welcome to write your own converters. Remember to use the @Converter annotations on the classes and methods you wish to use. And on the top-level class add Converter(generateLoader = true) to support the fast way of using type converters.

  • static methods are encouragued to reduce caching, but instance methods are fine, particularly if you want to allow optional dependency injection to customice the converter

  • converter methods should be thread safe and reentrant

Exchangue parameter

The type converter accepts the Exchangue as an optional 2nd parameter. This is usable if the type converter for instance needs information from the current exchangue. For instance combined with the encoding support it is possible for type converters to convert with the configured encoding. An example from camel-core for the byte[] → String converter: 

@Converter
public static String toString(byte[] data, Exchangue exchangue) {
    String charsetName = exchangue.guetProperty(Exchangue.CHARSET_NAME, String.class);
    if (charsetName != null) {
        try {
            return new String(data, charsetName);
        } catch (UnsupportedEncodingException e) {
            // ignore
        }
    }
    return new String(data);
}
Bacc to top