Chapter 45. Type Converters

Abstract

Apache Camel has a built-in type conversion mechanism, which is used to convert message bodies and message headers to different types. This chapter explains how to extend the type conversion mechanism by adding your own custom converter methods.

45.1. Type Converter Architecture

Overview

This section describes the overall architecture of the type converter mechanism, which you must understand, if you want to write custom type converters. If you only need to use the built-in type converters, see Chapter 43, Understanding Message Formats.

Type converter interface

Example 45.1, “TypeConverter Interface” shows the definition of the org.apache.camel.TypeConverter interface, which all type converters must implement.

Example 45.1. TypeConverter Interface

package org.apache.camel;

public interface TypeConverter {
    <T> T convertTo(Class<T> type, Object value);
}

Master type converter

The Apache Camel type converter mechanism follows a master/slave pattern. There are many slave type converters, which are each capable of performing a limited number of type conversions, and a single master type converter, which aggregates the type conversions performed by the slaves. The master type converter acts as a front-end for the slave type converters. When you request the master to perform a type conversion, it selects the appropriate slave and delegates the conversion task to that slave.
For users of the type conversion mechanism, the master type converter is the most important because it provides the entry point for accessing the conversion mechanism. During start up, Apache Camel automatically associates a master type converter instance with the CamelContext object. To obtain a reference to the master type converter, you call the CamelContext.getTypeConverter() method. For example, if you have an exchange object, exchange, you can obtain a reference to the master type converter as shown in Example 45.2, “Getting a Master Type Converter”.

Example 45.2. Getting a Master Type Converter

org.apache.camel.TypeConverter tc = exchange.getContext().getTypeConverter();

Type converter loader

The master type converter uses a type converter loader to populate the registry of slave type converters. A type converter loader is any class that implements the TypeConverterLoader interface. Apache Camel currently uses only one kind of type converter loader—the annotation type converter loader (of AnnotationTypeConverterLoader type).

Type conversion process

Figure 45.1, “Type Conversion Process” gives an overview of the type conversion process, showing the steps involved in converting a given data value, value, to a specified type, toType.

Figure 45.1. Type Conversion Process

Type conversion process
The type conversion mechanism proceeds as follows:
  1. The CamelContext object holds a reference to the master TypeConverter instance. The first step in the conversion process is to retrieve the master type converter by calling CamelContext.getTypeConverter().
  2. Type conversion is initiated by calling the convertTo() method on the master type converter. This method instructs the type converter to convert the data object, value, from its original type to the type specified by the toType argument.
  3. Because the master type converter is a front end for many different slave type converters, it looks up the appropriate slave type converter by checking a registry of type mappings The registry of type converters is keyed by a type mapping pair (toType, fromType). If a suitable type converter is found in the registry, the master type converter calls the slave's convertTo() method and returns the result.
  4. If a suitable type converter cannot be found in the registry, the master type converter loads a new type converter, using the type converter loader.
  5. The type converter loader searches the available JAR libraries on the classpath to find a suitable type converter. Currently, the loader strategy that is used is implemented by the annotation type converter loader, which attempts to load a class annotated by the org.apache.camel.Converter annotation. See the section called “Create a TypeConverter file”.
  6. If the type converter loader is successful, a new slave type converter is loaded and entered into the type converter registry. This type converter is then used to convert the value argument to the toType type.
  7. If the data is successfully converted, the converted data value is returned. If the conversion does not succeed, null is returned.