Transforming Message Content

Overview

FUSE Mediation Router supports a variety of approaches to transforming message content. In addition to a simple native API for modifying message content, FUSE Mediation Router supports integration with several different third-party libraries and transformation standards. The following kinds of transformations are discussed in this section:

Simple transformations

The Java DSL has a built-in API that enables you to perform simple transformations on incoming and outgoing messages. For example, the rule shown in Example 2.3 appends the text, World!, to the end of the incoming message body.

Example 2.3. Simple Transformation of Incoming Messages

from("SourceURL").setBody(body().append(" World!")).to("TargetURL");

Where the setBody() command replaces the content of the incoming message's body. You can use the following API classes to perform simple transformations of the message content in a router rule:

org.apache.camel.model.ProcessorType
org.apache.camel.builder.Builder
org.apache.camel.builder.ValueBuilder

ProcessorType class

The org.apache.camel.model.ProcessorType class defines the DSL commands you can insert directly into a router rule—for example, the setBody() command in Example 2.3. Table 2.2 shows the ProcessorType methods that are relevant to transforming message content:

Table 2.2. Transformation Methods from the ProcessorType Class

Method	Description
`Type convertBodyTo(Class type)`	Converts the IN message body to the specified type.
`Type convertFaultBodyTo(Class type)`	Converts the FAULT message body to the specified type.
`Type convertOutBodyTo(Class type)`	Converts the OUT message body to the specified type.
`Type removeFaultHeader(String name)`	Adds a processor which removes the header on the FAULT message.
`Type removeHeader(String name)`	Adds a processor which removes the header on the IN message.
`Type removeOutHeader(String name)`	Adds a processor which removes the header on the OUT message.
`Type removeProperty(String name)`	Adds a processor which removes the exchange property.
`ExpressionClause<ProcessorType<Type>> setBody()`	Adds a processor which sets the body on the IN message.
`Type setFaultBody(Expression expression)`	Adds a processor which sets the body on the FAULT message.
`Type setFaultHeader(String name, Expression expression)`	Adds a processor which sets the header on the FAULT message.
`ExpressionClause<ProcessorType<Type>> setHeader(String name)`	Adds a processor which sets the header on the IN message.
`Type setHeader(String name, Expression expression)`	Adds a processor which sets the header on the IN message.
`ExpressionClause<ProcessorType<Type>> setOutBody()`	Adds a processor which sets the body on the OUT message.
`Type setOutBody(Expression expression)`	Adds a processor which sets the body on the OUT message.
`ExpressionClause<ProcessorType<Type>> setOutHeader(String name)`	Adds a processor which sets the header on the OUT message.
`Type setOutHeader(String name, Expression expression)`	Adds a processor which sets the header on the OUT message.
`ExpressionClause<ProcessorType<Type>> setProperty(String name)`	Adds a processor which sets the exchange property.
`Type setProperty(String name, Expression expression)`	Adds a processor which sets the exchange property.

Builder class

The org.apache.camel.builder.Builder class provides access to message content in contexts where expressions or predicates are expected. In other words, Builder methods are typically invoked in the arguments of DSL commands—for example, the body() command in Example 2.3. Table 2.3 summarizes the static methods available in the Builder class.

Table 2.3. Methods from the Builder Class

Method	Description
`static <E extends Exchange> ValueBuilder<E> body()`	Returns a predicate and value builder for the inbound body on an exchange.
`static <E extends Exchange,T> ValueBuilder<E> bodyAs(Class<T> type)`	Returns a predicate and value builder for the inbound message body as a specific type.
`static <E extends Exchange> ValueBuilder<E> constant(Object value)`	Returns a constant expression.
`static <E extends Exchange> ValueBuilder<E> faultBody()`	Returns a predicate and value builder for the fault body on an exchange.
`static <E extends Exchange,T> ValueBuilder<E> faultBodyAs(Class<T> type)`	Returns a predicate and value builder for the fault message body as a specific type.
`static <E extends Exchange> ValueBuilder<E> header(String name)`	Returns a predicate and value builder for headers on an exchange.
`static <E extends Exchange> ValueBuilder<E> outBody()`	Returns a predicate and value builder for the outbound body on an exchange.
`static <E extends Exchange> ValueBuilder<E> outBody()`	Returns a predicate and value builder for the outbound message body as a specific type.
`static <E extends Exchange> ValueBuilder<E> systemProperty(String name)`	Returns an expression for the given system property.
`static <E extends Exchange> ValueBuilder<E> systemProperty(String name, String defaultValue)`	Returns an expression for the given system property.

ValueBuilder class

The org.apache.camel.builder.ValueBuilder class enables you to modify values returned by the Builder methods. In other words, the methods in ValueBuilder provide a simple way of modifying message content. Table 2.4 summarizes the methods available in the ValueBuilder class. That is, the table shows only the methods that are used to modify the value they are invoked on (for full details, see the API Reference documentation).

Table 2.4. Modifier Methods from the ValueBuilder Class

Method	Description
`ValueBuilder<E> append(Object value)`	Appends the string evaluation of this expression with the given value.
`ValueBuilder<E> convertTo(Class type)`	Converts the current value to the given type using the registered type converters.
`ValueBuilder<E> convertToString()`	Converts the current value a String using the registered type converters.
`ValueBuilder<E> regexReplaceAll(String regex, Expression<E> replacement)`	Replaces all occurrencies of the regular expression with the given replacement.
`ValueBuilder<E> regexReplaceAll(String regex, String replacement)`	Replaces all occurrencies of the regular expression with the given replacement.
`ValueBuilder<E> regexTokenize(String regex)`	Tokenizes the string conversion of this expression using the given regular expression.
`ValueBuilder<E> tokenize()`
`ValueBuilder<E> tokenize(String token)`	Tokenizes the string conversion of this expression using the given token separator.

Marshalling and unmarshalling

You can convert between low-level and high-level message formats using the following commands:

marshal()— Converts a high-level data format to a low-level data format.
unmarshal() — Converts a low-level data format to a high-level data format.

FUSE Mediation Router supports marshalling and unmarshalling of the following data formats:

Java serialization — Enables you to convert a Java object to a blob of binary data. For this data format, unmarshalling converts a binary blob to a Java object, and marshalling converts a Java object to a binary blob. For example, to read a serialized Java object from an endpoint, SourceURL, and convert it to a Java object, you use a rule like the following:
```
from("SourceURL").unmarshal().serialization()
.<FurtherProcessing>.to("TargetURL");
```
JAXB — Provides a mapping between XML schema types and Java types (see https://jaxb.dev.java.net/). For JAXB, unmarshalling converts an XML data type to a Java object, and marshalling converts a Java object to an XML data type. Before you can use JAXB data formats, you must compile your XML schema using a JAXB compiler to generate the Java classes that represent the XML data types in the schema. This is called binding the schema. After the schema is bound, you define a rule to unmarshal XML data to a Java object, using code like the following:
```
org.apache.camel.spi.DataFormat jaxb = new org.apache.camel.model.dataformat.JaxbDataFormat("GeneratedPackageName");

from("SourceURL").unmarshal(jaxb)
.<FurtherProcessing>.to("TargetURL");
```
where GeneratedPackagename is the name of the Java package generated by the JAXB compiler, which contains the Java classes representing your XML schema.
XMLBeans — Provides an alternative mapping between XML schema types and Java types (see http://xmlbeans.apache.org/). For XMLBeans, unmarshalling converts an XML data type to a Java object and marshalling converts a Java object to an XML data type. For example, to unmarshal XML data to a Java object using XMLBeans, you use code like the following:
```
from("SourceURL").unmarshal().xmlBeans()
.<FurtherProcessing>.to("TargetURL");
```
XStream — Provides another mapping between XML types and Java types (see http://xstream.codehaus.org/). XStream is a serialization library (like Java serialization), enabling you to convert any Java object to XML. For XStream, unmarshalling converts an XML data type to a Java object, and marshalling converts a Java object to an XML data type. For example, to unmarshal XML data to a Java object using XStream, you use code like the following:
```
from("SourceURL").unmarshal().xstream()
.<FurtherProcessing>.to("TargetURL");
```
Artix Data Services — FUSE Mediation Router also integrates with Artix Data Services, enabling you to integrate stub code generated by Artix Data Services. See Artix Data Services for details.

Artix Data Services

Artix Data Services is a powerful tool for converting documents and messages between different data formats. In Artix Data Services, you can use a graphical tool to define complex mapping rules (including processing of data content) and then generate stub code to implement the mapping rules. See Progress Artix Data Services home page and the Artix Data Services documentation for more details. The marshal() and unmarshal() DSL commands are capable of consuming Artix Data Services stub code to perform transformations on message formats. Example 2.4 shows a rule that unmarshals XML documents into a canonical format (Java objects) and then marshals the canonical format into the tag/value pair format.

Example 2.4. Using Artix Data Services to Marshal and Unmarshal

from("SourceURL").
unmarshal().artixDS(DocumentElement.class, ArtixDSContentType.Xml).
marshal().artixDS(ArtixDSContentType.TagValuePair).
    to("TargetURL");

	Note
	Artix Data Services is licensed separately from FUSE Mediation Router.