43.3. Built-In Type Converters

Overview

This section describes the conversions supported by the master type converter. These conversions are built into the Apache Camel core.
Usually, the type converter is called through convenience functions, such as Message.getBody(Class<T> type) or Message.getHeader(String name, Class<T> type). It is also possible to invoke the master type converter directly. For example, if you have an exchange object, exchange, you could convert a given value to a String as shown in Example 43.4, “Converting a Value to a String”.

Example 43.4. Converting a Value to a String

org.apache.camel.TypeConverter tc = exchange.getContext().getTypeConverter();
String str_value = tc.convertTo(String.class, value);

Basic type converters

Apache Camel provides built-in type converters that perform conversions to and from the following basic types:
  • java.io.File
  • String
  • byte[] and java.nio.ByteBuffer
  • java.io.InputStream and java.io.OutputStream
  • java.io.Reader and java.io.Writer
  • java.io.BufferedReader and java.io.BufferedWriter
  • java.io.StringReader
However, not all of these types are inter-convertible. The built-in converter is mainly focused on providing conversions from the File and String types. The File type can be converted to any of the preceding types, except Reader, Writer, and StringReader. The String type can be converted to File, byte[], ByteBuffer, InputStream, or StringReader. The conversion from String to File works by interpreting the string as a file name. The trio of String, byte[], and ByteBuffer are completely inter-convertible.
Note
You can explicitly specify which character encoding to use for conversion from byte[] to String and from String to byte[] by setting the Exchange.CHARSET_NAME exchange property in the current exchange. For example, to perform conversions using the UTF-8 character encoding, call exchange.setProperty("Exchange.CHARSET_NAME", "UTF-8"). The supported character sets are described in the java.nio.charset.Charset class.

Collection type converters

Apache Camel provides built-in type converters that perform conversions to and from the following collection types:
  • Object[]
  • java.util.Set
  • java.util.List
All permutations of conversions between the preceding collection types are supported.

Map type converters

Apache Camel provides built-in type converters that perform conversions to and from the following map types:
  • java.util.Map
  • java.util.HashMap
  • java.util.Hashtable
  • java.util.Properties
The preceding map types can also be converted into a set, of java.util.Set type, where the set elements are of the MapEntry<K,V> type.

DOM type converters

You can perform type conversions to the following Document Object Model (DOM) types:
  • org.w3c.dom.Document—convertible from byte[], String, java.io.File, and java.io.InputStream.
  • org.w3c.dom.Node
  • javax.xml.transform.dom.DOMSource—convertible from String.
  • javax.xml.transform.Source—convertible from byte[] and String.
All permutations of conversions between the preceding DOM types are supported.

SAX type converters

You can also perform conversions to the javax.xml.transform.sax.SAXSource type, which supports the SAX event-driven XML parser (see the SAX Web site for details). You can convert to SAXSource from the following types:
  • String
  • InputStream
  • Source
  • StreamSource
  • DOMSource

enum type converter

Camel provides a type converter for performing String to enum type conversions, where the string value is converted to the matching enum constant from the specified enumeration class (the matching is case-insensitive). This type converter is rarely needed for converting message bodies, but it is frequently used internally by Apache Camel to select particular options.
For example, when setting the logging level option, the following value, INFO, is converted into an enum constant:
<to uri="log:foo?level=INFO"/>
Because the enum type converter is case-insensitive, any of the following alternatives would also work:
<to uri="log:foo?level=info"/>
<to uri="log:foo?level=INfo"/>
<to uri="log:foo?level=InFo"/>

Custom type converters

Apache Camel also enables you to implement your own custom type converters. For details on how to implement a custom type converter, see Chapter 45, Type Converters.