Message Relay is a Message Pass through mechanism for ESB. Message relay enables ESB to pass the messages without building or processing the message.
When message relay is configured incoming requests to the ESB are not built and processed unless specifically requested to do so. A incoming message is wrapped inside a default SOAP envelope as binary content and sent through the ESB.
Some of the ESB scenarios doesn't require the full message to be built. Instead ESB can work on other message properties like request URLs or transport headers.
With message relay ESB can achieve a very high throughput.
Message relay has two main parts.
A message builder is used to build an incoming message to the ESB. A message formatter is used to build the out going stream from the message inside ESB.
So in a typical ESB routing scenario here is the flow
Client <---- Outgoing Message ----> Message Formatter <---- ESB <---- Message Builder <---- Incoming Message <---- Service Provider
Client <---- Outgoing Message ----> Message Formatter <---- ESB <---- Message Builder <---- Incoming Message <---- Service Provider
When Relay Message builder and formatter are specified for a content type, message coming with that content type will not be built by the ESB. Instead they will pass through the ESB as it is.
Message builders and formatters are specified in the axis2.xml under messageBuilders and messageFormatters configuration section. Message builders and formatters are chosen based on the content type of the message.
ESB has few default Message message builders. Even if the user doesn't specify them in the axis2.xml they will take effect. These can be overridden using the message builder configurations in the axis2.xml.
ESB doesn't have default Message formatters. So it is important to specify all of them in the axis2.xml configuration.
Here are the default message builders.
application/soap+xml | org.apache.axis2.builder.SOAPBuilder |
multipart/related | org.apache.axis2.builder.MIMEBuilder |
text/xml | org.apache.axis2.builder.SOAPBuilder |
application/xop+xml | org.apache.axis2.builder.MTOMBuilder |
application/xml | org.apache.axis2.builder.ApplicationXMLBuilder |
application/x-www-form-urlencoded | org.apache.axis2.builder.XFormURLEncodedBuilder |
In the axis2.xml file there are two configuration sections called messageBuilders and messageFormatters. User can replace the expected content types with the relay message builder and formattter to pass these messages through the ESB without building them.
Message relay builder and formatter class names.
builder : org.wso2.carbon.relay.BinaryRelayBuilder formatter : org.wso2.carbon.relay.ExpandingMessageFormatter
Sample configuration for message relay
<messageBuilders> <messageBuilder contentType="application/xml" class="org.wso2.carbon.relay.BinaryRelayBuilder"/> <messageBuilder contentType="application/x-www-form-urlencoded" class="org.wso2.carbon.relay.BinaryRelayBuilder"/> <messageBuilder contentType="multipart/form-data" class="org.wso2.carbon.relay.BinaryRelayBuilder"/> <messageBuilder contentType="text/plain" class="org.wso2.carbon.relay.BinaryRelayBuilder"/> <messageBuilder contentType="text/xml" class="org.wso2.carbon.relay.BinaryRelayBuilder"/> </messageBuilders>
<messageFormatters> <messageFormatter contentType="application/x-www-form-urlencoded" class="org.wso2.carbon.relay.ExpandingMessageFormatter"/> <messageFormatter contentType="multipart/form-data" class="org.wso2.carbon.relay.ExpandingMessageFormatter"/> <messageFormatter contentType="application/xml" class="org.wso2.carbon.relay.ExpandingMessageFormatter"/> <messageFormatter contentType="text/xml" class="org.wso2.carbon.relay.ExpandingMessageFormatter"/> <!--<messageFormatter contentType="text/plain" class="org.apache.axis2.format.PlainTextBuilder"/>--> <messageFormatter contentType="application/soap+xml" class="org.wso2.carbon.relay.ExpandingMessageFormatter"/> </messageFormatters>
Builder mediator can be used to build the actual SOAP message from a message coming in to ESB through the message relay. One usage is to use this before trying to log the actual message in case of a error. Also with the builder mediator ESB can be configured to build some of the messages while passing the others along.
Syntax of builder mediator
<syn:builder xmlns:syn="http://ws.apache.org/ns/synapse"> <syn:messageBuilder contentType="" class="" [formatterClass=""]/> </syn:builder>
By default builder mediator uses the axis2 default message builders for the content types specified in Table 1. User can override those by using the optional messageBuilder configuration.
Like in axis2.xml user has to specify the content type and the implementation class of the message builder. Also user can specify the message formatter for this content type. This is used by the ExpandingMessageFormatter to format the message before sending to the destination.
Now message relay has a axis2 module as well. This is an optional feature. This module can be used to build the actual SOAP message from the messages that went through the Message relay.
To enable this module user has to enable the relay module globally in the axis2.xml
<module ref="relay"/>
Also user has to put the following phase in to the InFlow of axis2.
<phase name="BuildingPhase"/>
This module is designed to be used by Admin Services that runs inside the ESB. All the admin services are running with content type: application/soap+xml. So if a user wants to use admin console and use the ESB for receiving message with content type application/soap+xml, this module should be used.
User can configure the module by going to the modules section in admin console and then going to the relay module. The module configuration is specified as a module policy. After changing the policy user has to restart the ESB for changes to take effect.
<wsp:Policy wsu:Id="MessageRelayPolicy" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" xmlns:wsmr="http://www.wso2.org/ns/2010/01/carbon/message-relay" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsmr:RelayAssertion> <wsp:Policy> <wsp:All> <wsmr:includeHiddenServices>false | false</wsmr:includeHiddenServices> <wsmr:services> <wsmr:service>Name of the service</wsmr:service>* </wsmr:services> <wsmr:builders> <wsmr:messageBuilder contentType="content type of the message" class="message builder implementation class" class="message formatter implementation class"/> </wsmr:builders> </wsp:All> </wsp:Policy> </wsmr:RelayAssertion> </wsp:Policy>
These are the assestions:
includeHiddenServices: If this is true message going to the services with hiddenService parameter will be built
wsmr:services: Messages going to these services will be built
wsmr:service: Name of the service
wsmr:builders: Message builders to be used for building the message
wsmr:builder: A message builder to be used for a content type