Breadcrumbs

Type Converters in Mappers

Overview

Type converters transform field values from one data type to another during mapping. Integration Manager provides built-in converters for common transformations like String-to-Decimal, String-to-Date, and String-to-Integer.

There are two ways to use converters:

  • converterExpression — references a built-in converter by name (no configuration needed)

  • converter — references a Spring bean by ID (built-ins auto-registered; custom converters defined in beans/ folder)

Complete XML Examples

Using converterExpression (Recommended for Built-ins)

The simplest way. No bean definitions needed — just reference the converter by name:

XML
<mappers>
    <loadMapper id="productMapper">
        <body in="sku" out="sku"/>
        <body in="price" out="attribute1" converterExpression="stringToDecimal"/>
        <body in="quantity" out="attribute2" converterExpression="stringToInteger"/>
        <body in="lastModified" out="attribute3" converterExpression="stringToDate"/>
    </loadMapper>
</mappers>

Using converter with Pre-Registered Bean Names

Built-in converters are also available as pre-registered Spring beans — reference by name with the converter attribute:

XML
<mappers>
    <loadMapper id="productMapper">
        <body in="price" out="attribute1" converter="stringToDecimal"/>
        <body in="quantity" out="attribute2" converter="stringToInteger"/>
        <body in="cost" out="attribute3" converter="stringToNumber"/>
        <body in="lastModified" out="attribute4" converter="stringToDate"/>
    </loadMapper>
</mappers>

Locale-Aware Decimal Conversion

For decimal formats that vary by locale (e.g., 1.234,56 in German vs 1,234.56 in English), pass the locale code in parentheses with converterExpression:

XML
<mappers>
    <loadMapper id="localeAwareMapper">
        <!-- German locale: expects comma as decimal separator -->
        <body in="germanPrice" out="attribute1" converterExpression="stringToDecimal(de)"/>

        <!-- French locale: expects comma as decimal separator -->
        <body in="frenchPrice" out="attribute2" converterExpression="stringToDecimal(fr)"/>

        <!-- US locale (default behavior): expects dot as decimal separator -->
        <body in="usPrice" out="attribute3" converterExpression="stringToDecimal(en)"/>
    </loadMapper>
</mappers>

Custom Converter (StringRight) via beans/ Folder

For converters that require constructor arguments (like StringRight), define the bean in the beans/ directory — not inline in the mapper file:

beans/converters.xml:

XML
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
           http://www.springframework.org/schema/beans/spring-beans.xsd">
    <bean id="stringRight7"
          class="net.pricefx.integration.mapper.converter.StringRight">
        <constructor-arg value="7"/>
    </bean>
</beans>

mappers/product-mapper.xml:

XML
<mappers>
    <loadMapper id="productMapper">
        <body in="sku" converter="stringRight7"/>
        <body in="name" out="label"/>
    </loadMapper>
</mappers>

How It Works

  1. converterExpression — references a built-in converter by name. Supports optional locale in parentheses, e.g., stringToDecimal(de). No bean definition needed.

  2. converter — references a Spring bean ID. Built-in converters are auto-registered by the IM framework. Custom converters must be defined in a file under beans/.

  3. Built-in converter names:

    • stringToDecimal — converts string to BigDecimal

    • stringToNumber — converts string to Number

    • stringToInteger — converts string to Integer

    • stringToDate — converts string to Date

  4. Converters are applied after the field value is read but before it is written to the output.

Common Pitfalls

  • Locale mismatch: If your source data uses German number format (1.234,56) but you do not specify the (de) locale, the conversion will fail or produce incorrect results.

  • converter vs converterExpression: converterExpression uses built-in converters directly. converter uses Spring bean IDs. Do not use a bean name in converterExpression — it will not find it.

  • Custom converters go in beans/: Never define <beans:bean> elements inside a mapper file. Custom converter beans belong in the beans/ directory as separate Spring XML files.

  • Null values: If the source field is null, converters may throw exceptions. Use a <groovy> expression with null checks for fields that might be empty.

  • includeUnmappedProperties: When false, only explicitly mapped fields appear in the output. When true (default), all source fields pass through.