Skip to content

Configuring Message Builders and Formatters

When a message comes into WSO2 API Manager Gateway, 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 API Gateway, 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. Given below is the typical workflow:

Default message builders and formatters

Listed below are the message formatters that are enabled for WSO2 API Manager by default:

Default message builders

Content Type Message builder class
application/xml org.apache.axis2.builder.ApplicationXMLBuilder
application/x-www-form-urlencoded org.apache.synapse.commons.builders.XFormURLEncodedBuilder
multipart/form-data org.apache.axis2.builder.MultipartFormDataBuilder
application/json org.apache.synapse.commons.json.JsonStreamBuilder
application/json/badgerfish org.apache.axis2.json.JSONBadgerfishOMBuilder
text/javascript org.apache.axis2.json.JSONBuilder
text/html org.wso2.carbon.relay.BinaryRelayBuilder
text/plain org.apache.axis2.format.PlainTextBuilder
application/octet-stream org.wso2.carbon.relay.BinaryRelayBuilder

Default message formatters

Content Type Message formatter class
application/x-www-form-urlencoded org.apache.axis2.transport.http.XFormURLEncodedFormatter
multipart/form-data org.apache.axis2.transport.http.MultipartFormDataFormatter
application/xml org.apache.axis2.transport.http.ApplicationXMLFormatter
text/xml org.apache.axis2.transport.http.SOAPMessageFormatter
application/soap+xml org.apache.axis2.transport.http.SOAPMessageFormatter
application/json org.apache.synapse.commons.json.JsonStreamFormatter
application/json/badgerfish org.apache.axis2.json.JSONBadgerfishMessageFormatter
text/javascript org.apache.axis2.json.JSONMessageFormatter
text/html org.apache.axis2.transport.http.ApplicationXMLFormatter
application/octet-stream org.wso2.carbon.relay.ExpandingMessageFormatter

Configuring default message builders and formatters

The default message builder or message formatter for a given content type can be changed or configured as follows.

  1. Open the <API-M_HOME>/repository/conf/deployment.toml file.

  2. You can specify a message builder or message formatter class for a given default content type by adding the following configuration.

    [message_builder]
    <content_type>="<message_builder_class>"
    
    [message_formatter]
    <content_type>="<message_formatter_class>"    
    
    [message_builder]
    application_xml = "org.apache.axis2.builder.ApplicationXMLBuilder"
    form_urlencoded = "org.apache.synapse.commons.builders.XFormURLEncodedBuilder"
    multipart_form_data = "org.apache.axis2.builder.MultipartFormDataBuilder"
    text_plain = "org.apache.axis2.format.PlainTextBuilder"
    application_json = "org.wso2.micro.integrator.core.json.JsonStreamBuilder"
    json_badgerfish = "org.apache.axis2.json.JSONBadgerfishOMBuilder"
    text_javascript = "org.apache.axis2.json.JSONBuilder"
    octet_stream = "org.wso2.carbon.relay.BinaryRelayBuilder"
    application_binary = "org.apache.axis2.format.BinaryBuilder"
    
    [message_formatter]
    form_urlencoded = "org.apache.synapse.commons.formatters.XFormURLEncodedFormatter"
    multipart_form_data = "org.apache.axis2.transport.http.MultipartFormDataFormatter"
    application_xml = "org.apache.axis2.transport.http.ApplicationXMLFormatter"
    text_xml = "org.apache.axis2.transport.http.SOAPMessageFormatter"
    soap_xml = "org.apache.axis2.transport.http.SOAPMessageFormatter"
    text_plain = "org.apache.axis2.format.PlainTextFormatter"
    application_json = "org.wso2.micro.integrator.core.json.JsonStreamFormatter"
    json_badgerfish = "org.apache.axis2.json.JSONBadgerfishMessageFormatter"
    text_javascript = "org.apache.axis2.json.JSONMessageFormatter"
    octet_stream = "org.wso2.carbon.relay.ExpandingMessageFormatter"
    application_binary = "org.apache.axis2.format.BinaryFormatter"
    
  3. Save the changes and restart the server to get the changes applied.

Custom message builders and formatters

In addition to default message formatters and builders, you can implement your own custom message builder or a formatter for a given content type as described in Writing a custom Message Builder and Formatter.

To enable the custom message builder or formatter, add the following configuration in the <API-M_HOME>/repository/conf/deployment.toml file, specifying the message builder/formatter class names against the content type.

[[custom_message_builders]]
content_type = "<content_type>"
class="<message_builder_class>"

[[custom_message_formatters]]
content_type = "<content_type>"
class="<message_formatter_class>"
[[custom_message_builders]]
content_type = "text/xml"
class="org.test.builder.http.CustomMessageBuilderForTextXml"

[[custom_message_formatters]]
content_type = "text/xml"
class="org.test.builder.http.CustomMessageFormatterForTextXml"