When a message comes in to the ESB profile of WSO2 Enterprise Integrator (WSO2 EI), the receiving transport selects a message builder based on the message's content type. It uses that builder to process the message's raw payload data and convert it into SOAP. Conversely, when sending a message out from ESB, a message formatter is used to build the outgoing stream from the message. As with message builders, the message formatter is selected based on the message's content type. In a typical routing scenario of the ESB, here is the flow:
You can use the messageType property to change the message's content type as it flows through ESB. For example, if the incoming message is in JSON format and you want to transform it to XML, you could add the messageType property before your mediators in the configuration:
Configuring message builders and formatters
Message builders and formatters are specified in
<EI_HOME>/conf/axis2/tenant-axis2.xml . if you are working in a multi-tenant environment), under the
messageFormatters configuration sections.
The ESB profile of WSO2 EI has a few default message builders, so even if you do not specify them explicitly in
tenant-axis2.xml, they will take effect when messages of those content types come into the ESB profile. If you want to use different builders, specify them in
tenant-axis2.xml to override the defaults. The ESB profile does not have default message formatters, so it is important to specify all of them in the
tenant-axis2.xml configuration. Following are the default message builders:
|Content type||Message Builder|
Handling illegal XML characters in plain text payloads
To use this feature in the current version of WSO2 EI, you need to get the latest product updates for your product. This feature is available as a product update from 2018-09-14 onwards. Note that you can deploy updates in a production environment only if you have a valid subscription with WSO2. Read more about WSO2 Updates.
Plain text payloads that contain illegal XML characters (such as unicodes) will not be successfully processed by the ESB. Therefore, you must configure the system to replace the illegal characters in the payload with an actual character. To enable this configuration, add the parameter shown below (with a suitable unicode value) to the
XMLOutputFactory.properties file (stored in the
<EI_HOME>/ directory). If this file does not exist in your product by default, be sure to create a new file.
When this configuration is enabled, all the illegal characters found in a payload will be replaced with the actual character that is represented by the unicode value that you specify for the parameter. The below example uses whitespaces (represented by by the '\u0020' unicode value) to replace illegal characters in payloads.
Using message relay
If you want to enable message relay, so that messages of a specific content type are not built or formatted but simply pass through the ESB, you can specify the message relay builder (
org.wso2.carbon.relay.BinaryRelayBuilder) for that content type. For more information, see Configuring Message Relay.
Handling messages with no content type
To ensure that messages with no content type are handled gracefully without causing errors, add the following to
- In the parameters section:
<parameter name="defaultContentType" locked="false">empty/content</parameter>
- In the message builders section:
<messageBuilder contentType="empty/content" class="org.wso2.carbon.relay.BinaryRelayBuilder"/>
- In the message formatters section:
<messageFormatter contentType="empty/content" class="org.wso2.carbon.relay.ExpandingMessageFormatter"/>
Handling text/csv messages
There is no default builder or formatter for messages with the text/csv content type. If you just want to pass these messages through the ESB, you can configure the message relay builder and formatter. If you want to process these messages, you can access the content inside the request/response payload of CSV by configuring the
org.apache.axis2.format.PlainTextFormatter for the text/csv content type in
axis2.xml. For example:
When a text/csv message comes into the ESB, the log will include an entry similar to the following, and you can observe that the CSV data is placed inside the payload: