Enterprise Integration Zone is brought to you in partnership with:

I'm an Enterprise Software Architect working predominantly on integration solutions in the financial software arena. Core competencies include Java, Message Driven Architectures, Spring, Spring Integration and data storage technologies. Matt is a DZone MVB and is not an employee of DZone and has posted 13 posts at DZone. You can read more from them at their website. View Full User Profile

Spring and C24 iO - Part 2 C24 Spring Integration

06.28.2012
| 5803 views |
  • submit to reddit
The focus for Part 2 of the series (Spring and C24 iO - Accelerating Enterprise Data Services Deployment) concentrates on integration namespace capabilities that have been provided by C24 for building integration flows and, through example, explores the use of C24 iO within those flows.


Some contextual information may be required in order to better understand the example code and configuration. SWIFT is a messaging standard used by most of the world's financial institutions. If you've not come across them before, SWIFT messages look like someone has danced on a keyboard so don't worry about understanding the content. The important aspect is that it's a message type that is standard, well adopted and complex enough that it's difficult to write custom code in order to parse. SWIFT messages (ISO-15022) are usually specified by type using a number, so, in this example you will encounter an MT540 SWIFT message, this is a Receive Free message sent from an account owner to an account servicer. If you don't know SWIFT but you either use C24 iO or perhaps are thinking about it, read on, it's not a major obstacle.


C24 Spring Integration Namespace Support 

C24 Spring Core provides capability to use iO model objects as Spring beans using very simple XML namespace or @Configuration annotated classes to populate the Spring container.

The Spring Integration framework provides capability for Spring Integration Messages (org.springframework.integration.Message) to be handled in a uniform way by integration constructs such as gateways, splitters, aggregators, header enrichers, filters and transformers; that list is not exhaustive. These integration constructs have no knowledge of message payloads, their types or their content.

Although the Spring Integration framework offers a set of constructs that support lightweight messaging, it does not natively support specialist data-binding, transformation and validation as this would require a more intimate knowledge of the message payload as well as tooling around message models, validations and transformations. Spring Integration provides the facility to plugin code that can perform those functions, i.e. via Service Activators, but this means that configuration and distribution of that code is much more difficult, i.e. it would always result in developers having to write and share custom Service Activator (Java) code. This is a requirement that we are really trying to avoid as there is a much more attractive solution available. SpringSource has partnered with C24 to provide native capability around 12 three core aspects of message processing: 1) specialist binding, 2) validation and 3) transformation.
 
Extending the semantically rich offerings of Spring Integration constructs by adding C24 iO capability required doing two things. Firstly, a namespace was constructed that specified syntactic requirements for those three types of message processing construct. Secondly, a set of Spring Integration beans have been built that are able to process iO model objects as Spring Integration message payloads. 

This work was undertaken by SpringSource  engineers early in 2011. The partnership between C24 and SpringSource has resulted in native capability within Spring Integration to process iO model objects in ways described in the following sections.

C24 Namespace Constructs

iO Object Unmarshalling-Transformer

The C24 Spring Integration Unmarshalling Transformer construct provides capability for the Spring Integration Framework to receive a message in any supported data format and output it as a C24 iO model object.

By way of example, the Spring Framework may supply a raw SWIFT MT541 message String (as shown in Diagram 3) to the transformer below. The result is that an MT541 model object will be returned. Note that no custom Java code had to be written in order for this to happen, merely simple namespace configuration.
The Unmarshalling Transformer namespace construct to use for this purpose is:
<c24:unmarshalling-transformer
        id="c24Mt541UnmarshallingTransformer"
        source-factory-ref="textualSourceFactory"
        model-ref="mt541Model" input-channel=”unmarshall-channel”
        output-channel=”enrichment-channel”/>

The source-factory-ref is the name of the parser that will bind the input to this transformer into an object described by the bean reference model-ref.



iO Object Marshalling-Transformer



The C24 Spring Integration Marshalling Transformer construct provides capability for the Spring Integration Framework to pass in a C24 iO model object and output it in an alternative, and configurable, format. In the example below, a message containing an iO model object can be passed-in, a JSON (java.lang.String) representation of the object is returned.




Note that an output format is chosen by specifying a sink-factory attribute on the marshalling element. The Marshalling Transformer namespace construct to use for this purpose is:
<c24:marshalling-transformer
        sink-factory="biz.c24.io.spring.sink.JsonSinkFactory"
        output-type="STRING"   
        input-channel=”marshall-channel”
        output-channel=”storage-channel”/>

Some of the sink-factory attributes that are currently supported are for: XML, JSON, CSV and Java Source. 

iO Object Transformer

The C24 Spring Integration Transformer construct provides capability for the Spring Integration Framework to pass in a C24 iO model object and receive output as another C24 iO model object.

In most cases the source and target iO model object are different types, but that’s certainly not a prerequisite for transformation. The single most significant parameter is the one that identifies the target or output iO model object type.
The Transformer namespace construct to use for this purpose is:
<c24:transformer
        transform-class="biz.c24.io.swift2012...MT541ToFlatTransform"
         input-channel="transformation-channel"
        output-channel="reply-channel"
          always-return-array="false"/>

iO Object Validating Header Enricher

The C24 Spring Integration Validating Header Enricher is a type of transformer that provides capability for the Spring Integration Framework to pass in a C24 iO model object and receive output in the form of validation results.

Results are loaded as [K,V] pairs into the Spring Integration header, this means that they can be accessed by other integration constructs or even SpEL expressions directly.
The Validating Header Enricher namespace construct to use for this purpose is:
<c24:validating-header-enricher
        fail-events="true" pass-events="true"   statistics="true"/>

The result of using the construct in this way will mean that all fail events get loaded into an SI message header named “c24_failEvents”, all pass events into a header named “c24_passEvents”, and statistics for those operations into a header named “c24_statistics”. Default values for that namespace are true for fail events, false for pass events and statistics.


iO Object XPath Transformer

The C24 iO XPath Transformer is a type of transformer that provides capability for the Spring Integration Framework to pass in a C24 iO model object and receive output data of various types including object, string, boolean and list. The data that’s obtained from using this integration construct is derived directly from the iO model object payload.

The XPath Transformer namespace construct to for this purpose is:

<int-c24:xpath-transformer input-channel="..."
        evaluation-type="OBJECT_RESULT"
        xpath-statement="/MT541Message/Block4/SeqB/Field90aPrice"
        input-channel=”price-lookup-channel”
          output-channel="deal-price-recorder-channel"/>


iO Object XPath Router

The C24 Xpath Router is a type of message router that provides capability for the Spring Integration Framework to pass in a C24 iO model and have messages routed to a specified channel determined by an XPath expression.
This router is much the same as the pure Spring Integration router except that support is added that enables iO model objects to be routed to channels, determined by XPath expression results invoked against that data.
The XPath Router construct to use for this purpose is:

             
<c24:xpath-router
        xpath-statement="/MT541Message/Block4/SeqA/.../G/Function"
        input-channel="message-router-channel">
            <c24:mapping channel="new-message-channel"
                value="NEWM"/>
                <c24:mapping channel="cancellation-message-channel"
                value="CANC"/>
                <c24:mapping channel="preadvice-message-channel"
                value="PREA"/>
    </c24:xpath-router> 


As with a standard router configuration, you can also specify a default-output-channel that’s used if a single message channel cannot be chosen from the set provided. It is also possible to configure a bean reference that can be used to provide the XPath statement.

iO Object XPath Selector

The C24 XPath Selector is a type of Filter that provides capability for the Spring Integration Framework to pass in a C24 iO model object and determine if the message will continue to undergo processing. That decision is based on the result of a comparison between payload content data and data provided in the namespace construct. If the message is not filtered it will be returned as the payload to the Spring Integration Framework, otherwise it is discarded.

The XPath Selector namespace construct used for this purpose is:
<c24:xpath-selector
        evaluation-result-type="boolean"
        xpath-statement="/MT541Message/Block4/SeqA/.../G/Function"
        string-test-value="CANC"/>

In this example, only SWIFT messages that have a cancellation function will continue to undergo processing, all others will be discarded. Once again, the XPath statement can also be supplied as a reference to a Spring bean.

C24 Namespace Examples

Given a @Configuration class such as the following, two beans will become available from within the Spring container. Firstly, the textualSourceFactory is the factory object that will provide the instance of the SWIFT parser to any namespace construct that requires it. Secondly, an MT541 model object will also be made available to any namespace construct that requires it, i.e. any namespace construct that performs marshalling/unmarshalling or transformation involving MT541 models.


@Configuration
public class C24SpringConfiguration {

    @Bean(name = "textualSourceFactory")
    public TextualSourceFactory getTextualSourceFactory() {
      TextualSourceFactory textualSourceFactory 

          = new TextualSourceFactory();
      textualSourceFactory.setEncoding("UTF-8");
      return textualSourceFactory;
    }

    @Bean(name = "mt541Model")
    public C24Model getMT541Model() {
      Element element 

        = new biz.c24.io.swift2011.MT541Element();
      return new C24Model(element);
    }
}


Of course, you don't have to use a @Configuration class to populate the Spring container, you can use an XML descriptor to declare the beans instead.
The sample project reads a raw SWIFT message and then progresses it through a series of pipes and filters. The single namespace construct that binds a raw SWIFT MT541 into Java code is the following.
<c24:unmarshalling-transformer 

      id="c24Mt541UnmarshallingTransformer"
      source-factory-ref="textualSourceFactory" 

      model-ref="mt541Model"/>


That's all that's necessary to convert a raw SWIFT message like this:

{1:F01DRESGB2LAXXX0548034693}{2:O5410947040127FRNYUS33AXXX42181834250401270947N}{3:{108:valid}}{4:
:16R:GENL
:20C::SEME//FRTJ123REC2
:23G:NEWM
:16S:GENL
:16R:TRADDET
:98A::TRAD//20000519
:98A::SETT//20000524
:90A::DEAL//PRCT/101,001283
:35B:ISIN GB0987654321
:16S:TRADDET
:16R:FIAC
:36B::SETT//FAMT/4000000,
:97A::SAFE//222S
:16S:FIAC
:16R:SETDET
:22F::SETR//TRAD
:16R:SETPRTY
:95P::SELL//DEUTDEFF
:16S:SETPRTY
:16R:SETPRTY
:95R::DEAG/CRST/456
:16S:SETPRTY
:16R:SETPRTY
:95R::REAG/CRST/123
:16S:SETPRTY
:16R:SETPRTY
:95P::RECU//DRESDEFF
:16S:SETPRTY
:16R:SETPRTY
:95P::BUYR//MGTCDE55
:97A::SAFE//111S
:16S:SETPRTY
:16R:SETPRTY
:95P::PSET//CRSTGB22
:16S:SETPRTY
:16R:AMT
:19A::SETT//GBP4047151,3
:16S:AMT
:16S:SETDET
-}

into a C24 Java object. Once that's done, as a developer you can change SWIFT message values, perform semantic validation or anything else that you choose to do with the Java object.
The sample project contains a number of C24 models and transformations, we've looked at the MT541 model but what about transformations? In order to transform data from one form or type to another we can use a C24 iO transformer. These transformers take data contained in a source model object and transfer them into a target model object. These two models can be the same type but more often than not, the transformation takes place between two distinct models.
The object that is passed into the C24 iO transformer namespace construct is already defined by a model (it can't be a C24 iO object otherwise), so the only other configuration that is necessary to trigger a transformation into a target object is a reference to the transformation model itself. As in the example project, that can be achieved using the following configuration:
<c24:transformer 

  transform-class="..swift2011..MT541ToFlatTransform"
  input-channel="mt541-transformation-channel"
  output-channel="transformation-gw-reply-channel"
  always-return-array="false"/>


The transformation class, automatically generated by C24 iO during deployment of the transformation model, will receive the MT541Message that's passed into it and output a single XML string. This XML string automatically becomes the Spring Integration message payload and will be delivered to the next namespace construct in the flow by the Spring Integration payload.
This is just a very small and specific taster of C24 Spring samples, further examples will be published in future articles.
Published at DZone with permission of Matt Vickery, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)