Chapter 17. Context Mapping

17.1. Context Mapper

A ContextMapper moves native binding message headers and/or properties to and from SwitchYard's canonical context. The default ContextMapper implementations are used by their associated bindings but can be overridden by the user.

17.2. Create a Custom Context Mapper

Procedure 17.1. Create a Custom Context Mapper

  1. Implement the org.switchyard.component.common.composer.ContextMapper interface:
    public interface ContextMapper<T> {
        void mapFrom(T source, Context context) throws Exception;
        void mapTo(Context context, T target) throws Exception;
    }
    
  2. Specify your implementation in your switchyard.xml file:
    <binding.xyz ...>
        <contextMapper class="com.example.MyContextMapper"/>
    </binding.xyz>
    
  3. Alternatively, you can implement the org.switchyard.component.common.composer.RegexContextMapper interface, which adds regular expression support:
    public interface RegexContextMapper<T> extends ContextMapper<T> {
        ContextMapper<T> setIncludes(String includes);
        ContextMapper<T> setExcludes(String excludes);
        ContextMapper<T> setIncludeNamespaces(String includeNamespaces);
        ContextMapper<T> setExcludeNamespaces(String excludeNamespaces);
        boolean matches(String name);
        boolean matches(QName qname);
    }
    

17.3. Custom Context Mapper Properties

  • Your mapFrom() method needs to map a source native message's properties to the SwitchYard Message's Context.
  • Your mapTo() method needs to map a SwitchYard Message's Context properties into the target native message.
  • If you extend BaseContextMapper, these methods are canceled with "no-op" implementations so you only have to implement what you wish.
If you are adding regular expression, support, note the following:
  • The setIncludes(), setExcludes(), setIncludeNamespaces() and setExcludeNamespaces() methods are just bean properties. The matches() methods use those bean properties to determine if the specified name or qualified name passes the collective regular expressions.
  • If you extend the BaseRegexContextMapper, all of these are implemented for you. Then, in your implementation's mapFrom and mapTo methods, you only need to first check if the property matches before you map it.
Also for RegexContextMapper, the following additional attributes of the <contextMapper/> element are used:
includes
This indicates which context property names to include.
excludes
This indicates which context property names to exclude.
includeNamespaces
This indicates which context property namespaces to include (if the property name is a qualified name).
excludeNamespaces
This indicates which context property namespaces to exclude (if the property name is a qualified name).

17.4. Context Mapper Implementations Available Out-of-the-Box

The following four out-of-the-box implementations extend BaseRegexContextMapper, thus each of them can be configured to use the additional regular expression attributes.
SOAPContextMapper
When processing an incoming SOAPMessage, the SOAPContextMapper takes the MIME (in most cases, HTTP) headers from a SOAP envelope and maps them into the SwitchYard Context as Scope.IN properties with the SOAPComposition.SOAP_MESSAGE_MIME_HEADER label, and takes the SOAP header elements from the soap envelope and maps them into the SwitchYard Context as Scope.EXCHANGE properties with the SOAPComposition.SOAP_MESSAGE_HEADER label. When processing an outgoing SOAPMessage, it takes the SwitchYard Scope.OUT Context properties and maps them into mime (in most cases, HTTP) headers, and takes the SwitchYard Scope.EXCHANGE Context properties and maps them into the SOAP envelope as soap header elements.

Note

The SOAPContextMapper has an additional attribute that the other OOTB ContextMappers do not use, namely soapHeadersType:
<binding.soap>
    <contextMapper includes=".*" soapHeadersType="VALUE"/>
</binding.soap>
The value of soapHeadersType can be CONFIG, DOM, VALUE or XML (and correspond to the enum SOAPHeadersType.CONFIG, DOM, VALUE or XML). With CONFIG, each soap header element is mapped into an org.switchyard.config.Configuration object, with DOM, each soap header element is left as is (a DOM element), with VALUE, only the String value of each soap header element is stored, and with XML, each soap header element is transformed into an XML String.
CamelContextMapper
When processing an incoming CamelMessage, the CamelContextMapper takes the CamelMessage headers and maps them into the SwitchYard Context as Scope.IN properties with the CamelComposition.CAMEL_MESSAGE_HEADER label, and takes the Camel Exchange properties and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the CamelComposition.CAMEL_EXCHANGE_PROPERTY label. When processing an outgoing CamelMessage, it takes the SwitchYard Scope.OUT Context properties and maps them into the CamelMessage as headers, and takes the SwitchYard Scope.EXCHANGE Context properties and maps them into the Camel Exchange as properties.
HttpContextMapper
When processing an incoming HTTP request, the HttpContextMapper takes the incoming request headers and maps them into the SwitchYard Context as Scope.IN with the HttpComposition.HTTTP_HEADER label. When processing an outgoing HTTP response, it takes the SwitchYard Scope.OUT Context properties and maps them into the response headers.
RESTEasyContextMapper
When processing an incoming HTTP request, the RESTEasyContextMapper takes the incoming request headers and maps them into the SwitchYard Context as Scope.IN with the RESTEasyComposition.HTTP_HEADER label. When processing an outgoing HTTP response, it takes the SwitchYard Scope.OUT Context properties and maps them into the response headers.
The JCA Component provides three different ContextMappers:
IndexedRecordContextMapper
When processing an incoming IndexedRecord, the IndexedRecordContextMapper takes the record name and record short description and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the JCAComposition.JCA_MESSAGE_PROPERTY label. When processing an outgoing IndexedRecord, it looks for those properties specifically in the SwitchYard.EXCHANGE Context properties by key and sets them on the IndexedRecord.
MappedRecordContextMapper
When processing an incoming MappedRecord, the MappedRecordContextMapper takes the record name and record short description and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the JCAComposition.JCA_MESSAGE_PROPERTY label. When processing an outgoing MappedRecord, it looks for those properties specifically in the SwitchYard.EXCHANGE Context properties by key and sets them on the MappedRecord.
JMSContextMapper
When processing an incoming (JMS) Message, the JMSContextMapper takes the Message properties and maps them into the SwitchYardContext as Scope.EXCHANGE properties with the JCAComposition.JCA_MESSAGE_PROPERTY label. When processing an outgoing (JMS) Message, it takes the SwitchYard.EXCHANGE Context properties and maps them into the Message as Object properties.