Chapter 42. 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.
42.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 40, Understanding Message Formats.
Type converter interface
Example 42.1, “TypeConverter Interface” shows the definition of the
org.apache.camel.TypeConverter
interface, which all type converters must implement.
Example 42.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 42.2, “Getting a Master Type Converter”.
Example 42.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 42.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 42.1. Type Conversion Process
The type conversion mechanism proceeds as follows:
- The
CamelContext
object holds a reference to the masterTypeConverter
instance. The first step in the conversion process is to retrieve the master type converter by callingCamelContext.getTypeConverter()
. - 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 thetoType
argument. - 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'sconvertTo()
method and returns the result. - 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.
- 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”. - 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 thetoType
type. - If the data is successfully converted, the converted data value is returned. If the conversion does not succeed,
null
is returned.