Description of message transformers and builders
Today we will discuss message transformers (formatters) and builders, an essential part of the functioning of WSO2 Enterprise Integrator (EI).
Both elements can be used to transform and manage incoming messages through builders, or outgoing messages through formatters, automatically. Enterprise Integrator will take the ‘Content-type’ header as a basis and, based on this, it will translate the message one way or the other. The translation will be performed before and after its mediation takes place, as shown in the following image:
In the case of a message builder, we can see an example of its functioning if we set the ‘Content-type’ to ‘application/xml’ or ‘application/json’ and send a message of the other type. In this case, an internal error will be generated in the EI, since it would try to transform a message of one type, when it has been told that the message is of another, specific type. If we set the right ‘Content-type’, it would transform the message correctly and include it as part of the body of the SOAP message.
For the case of the message transformer, we can see its functioning using the following practical example. Here we have an output sequence that will generate an XML message through a payloadFactory mediator, but before sending that message back, we change the ‘Content-type’ to ‘application/json’.
Output sequence:
<sequence name="exitJSON" xmlns="http://ws.apache.org/ns/synapse">
<payloadFactory media-type="xml">
<format>
<exit>
<valueType>JSON</valueType>
</exit>
</format>
</payloadFactory>
<property name="messageType" scope="axis2" type="STRING" value="application/json"/>
<property name="ContentType" scope="axis2" type="STRING" value="application/json"/>
<send/>
</sequence>
After exiting the sequence, the corresponding ‘Message Formatter’ would start working, and therefore, we would see the message in JSON format. Output:
{ "exit": { "valueType": "JSON" } }
Base product transformations
These elements are configured in the ‘${EI_HOME}/conf/axis2/axis2.xml’ file, within their corresponding sections (messageBuilders and messageFormatters XML elements, respectively). And by default, EI will already include certain preconfigured base ‘Content-type’, which are:
- application/octet-stream
- application/x-www-form-urlencoded
- application/json
- application/xml
- multipart/form-data
- text/plain
- application/soap+xml : only for messageBuilders
- text/xml : only for messageBuilders
Each of them is linked to a Java class that will perform the corresponding transformation. And if we indicate some other ‘Content-type’ as output, as we have seen, it can lead to an error within our integration.
To avoid this type of issue, we can configure new messageBuilders and/or messageFormatters XML elements within the ‘axis2.xml’ file associated with the ‘Content-type’ that we want to have handled by EI.
Transformations without a linked ‘Content-type’
EI also allows us to configure messageBuilders and/or messageFormatters XML elements for cases where the ‘Content-type’ is not included. In this way, we can have a default handling and avoid improperly handled responses. We will configure this in the ‘axis2.xml’ file by following these steps:
- Adding the ‘defaultContentType’ parameter with the ‘empty/content’ value
- Adding a new messageBuilders XML element associated with the ‘Content-type’ ‘empty/content’ and the transformation class that we want (it can be any one of those already configured in other messageBuilders).
- Adding a new messageFormatters XML element associated with the ‘Content-type’ ‘empty/content’, and the class that can be used to transform the message the way we want.
Ad-hoc transformations
On the other hand, we can also configure certain transformations for different messages using a specific ‘Content-type’. The currently existing transformation classes may not be enough, and we may have a specific unaddressed default need for a specific ‘Content-type’. As a solution, we can create our own ‘Message Builders’ or ‘Message Formatters’. To do this, we must create Java classes that implement the ‘org.apache.axis2.builder.Builder’ or ‘org.apache.axis2.transport.MessageFormatter’ interfaces, including the libraries that contain those classes and configure the specific elements in the ‘axis2.xml’ file.
Avoid the transformation
Lastly, it is also possible to tell EI that a specific ‘Content-type’ must not be handled by the ESB. To do this, in the ‘axis2.xml’ file we must configure the desired ‘Content-type’ with the ‘org.wso2.carbon.relay.BinaryRelayBuilder’ class for ‘Message Builders’ or the ‘org.wso2.carbon.relay.ExpandingMessageFormatter’ class for ‘Message Formatters’.
This may be a good practice in the case that we have an API with many resources that display information with different file formats. If we want them to be treated as binary and for the browser to be tasked with opening them properly, we could configure each ‘Content-type’ as per the ‘Message Builders’ or ‘Message Formatters’ described above.
With this, we have learned a little more about the functioning of one of the basic aspects of data and system integration: the transformation of different messages within a data bus.
