diff --git a/src/docbkx/resources/images/bank-router.png b/src/docbkx/resources/images/bank-router.png new file mode 100644 index 0000000000..8191565440 Binary files /dev/null and b/src/docbkx/resources/images/bank-router.png differ diff --git a/src/docbkx/resources/images/cafe-eip.png b/src/docbkx/resources/images/cafe-eip.png new file mode 100644 index 0000000000..12cd96ec61 Binary files /dev/null and b/src/docbkx/resources/images/cafe-eip.png differ diff --git a/src/docbkx/resources/images/chain.png b/src/docbkx/resources/images/chain.png new file mode 100644 index 0000000000..df4b635002 Binary files /dev/null and b/src/docbkx/resources/images/chain.png differ diff --git a/src/docbkx/resources/images/gateway.png b/src/docbkx/resources/images/gateway.png new file mode 100644 index 0000000000..8a2088cda0 Binary files /dev/null and b/src/docbkx/resources/images/gateway.png differ diff --git a/src/docbkx/resources/images/loan-broker-eip.png b/src/docbkx/resources/images/loan-broker-eip.png new file mode 100644 index 0000000000..06fa75d92b Binary files /dev/null and b/src/docbkx/resources/images/loan-broker-eip.png differ diff --git a/src/docbkx/resources/images/quotes-aggregator.png b/src/docbkx/resources/images/quotes-aggregator.png new file mode 100644 index 0000000000..34364224e5 Binary files /dev/null and b/src/docbkx/resources/images/quotes-aggregator.png differ diff --git a/src/docbkx/samples.xml b/src/docbkx/samples.xml index 854e2afa18..1992780cf7 100644 --- a/src/docbkx/samples.xml +++ b/src/docbkx/samples.xml @@ -149,13 +149,251 @@ That includes Samples, so if you can't find what you are looking for let us know
Loan Broker + + In this section, we will review a Loan Broker sample application that is included in the + Spring Integration samples. This sample is inspired by one of the samples featured in Gregor + Hohpe's Ramblings. + + The diagram below represents the entire process + + + + + + + + + + + Now lets look at this process in more details + + At the core of EIP architecture are the very simple yet powerful concepts of Pipes and Filters and Message. Endpoints (Filters) are + connected with one another via Channels (Pipes). The producing endpoint sends Message to the Channel and the Message is retrieved + by the Consuming endpoint. This architecture is meant to define various mechanisms that describe How information is exchanged between + the endpoints, without any awareness of What those endpoints are or What information they are exchanging, thus providing for a very loosely + coupled and flexible collaboration model while also, decoupling Integration concerns from Business concerns. EIP extends this architecture + by further defining: + + + The types of pipes (Point-to-Point Channel, Publish-Subscribe Channel, Channel Adapter, etc.) + + + + The core filters and patterns around how filters collaborate with pipes + (Message Router, Splitters and Aggregators, various Message Transformation patterns, etc.) + + + + + The details and variations of this use case are very nicely described in Chapter 9 of the EIP Book, but here is the brief summary; + A Consumer while shopping for the best Loan Quote(s) subscribes to the services of a Loan Broker, which handles details such as: + + + Consumer pre-screening (e.g., obtain and review the consumer's Credit history) + + + + Determine the most appropriate Banks (e.g., based on consumer's credit history/score) + + + + Send a Loan quote request to each selected Bank + + + Collect responses from each Bank + + + Filter responses and determine the best quote(s), based on consumer's requirements. + + + Pass the Loan quote(s) back to the consumer. + + + + + Obviously the real process of obtaining a loan quote is a bit more complex, but since our goal here is to demonstrate how + Enterprise Integration Patterns are realized and implemented within SI, the use case has been simplified to concentrate only on + the Integration aspects of the process. It is not an attempt to give you an advice in consumer finances. + + + As you can see, by hiring a Loan Broker, the consumer is isolated from the details of the Loan Broker's operations, and each Loan Broker's + operations may defer from one another to maintain competitive advantage, so whatever we assemble/implement must be flexible so any changes + could be introduced quickly and painlessly. + Speaking of change, the Loan Broker sample does not actually talk to any 'imaginary' Banks or Credit bureaus. Those services are stubbed out. + Our goal here is to assemble, orchestrate and test the integration aspect of the process as a whole. Only then can we start thinking about + wiring such process to the real services. At that time the assembled process and its configuration will not change regardless of the number + of Banks a particular Loan Broker is dealing with, or the type of communication media (or protocols) used (JMS, WS, TCP, etc.) + to communicate with these Banks. + + DESIGN + + As you analyze the 6 requirements above you'll quickly see that they all fall into the category of Integration concerns. + For example, in the consumer pre-screening step we need to gather additional information about the consumer and the consumer's desires + and enrich the loan request with additional meta information. We then have to filter such information to select the most appropriate list of + Banks, and so on. Enrich, filter, select – these are all integration concerns for which EIP defines a solution in the form of patterns. + SI provides an implementation of these patterns. + + Messaging Gateway + + + + + + + + + + + The Messaging Gateway pattern provides a simple mechanism to access messaging systems, including our Loan Broker. + In SI you define the Gateway as a Plain Old Java Interface (no need to provide an implementation), configure it via the + XML <gateway&gr; element or via annotation and use it as any other Spring bean. SI will take care of + delegating and mapping method invocations to the Messaging infrastructure by generating a Message (payload is mapped to an + input parameter of the method) and sending it to the designated channel. + + +
+ +]]> + + + Our current Gateway provides two methods that could be invoked. One that will return the best single quote and another one that + will return all quotes. Somehow downstream we need to know what type of reply the caller is looking for. The best way to achieve + this in Messaging architecture is to enrich the content of the message with some meta-data describing your intentions. + Content Enricher is one of the patterns that addresses this and although Spring Integration does provide a + separate configuration element to enrich Message Headers with arbitrary data (we'll see it later), as a convenience, since + Gateway element is responsible to construct the initial Message it provides embedded + capability to enrich the newly created Message with arbitrary Message Headers. In our + example we are adding header RESPONSE_TYPE with value 'BEST'' whenever the getBestQuote() method is invoked. For other method + we are not adding any header. Now we can check downstream for an existence of this header and based on its presence and its value + we can determine what type of reply the caller is looking for. + + + + Based on the use case we also know there are some pre-screening steps that needs to be performed such as getting and evaluating the consumer's + credit score, simply because some premiere Banks will only typically accept quote requests from consumers that meet a minimum credit + score requirement. So it would be nice if the Message would be enriched with such information before it is forwarded + to the Banks. It would also be nice if when several processes needs to be completed to provide such meta-information, those + processes could be grouped in a single unit. In our use case we need to determine credit score and based on the credit score and some + rule select a list of Message Channels (Bank Channels) we will sent quote request to. + + Composed Message Processor + + The Composed Message Processor pattern describes rules around building endpoints that maintain control over message flow which + consists of multiple message processors. In Sprig Integration Composed Message Processor pattern is implemented via + <chain> element. + + + + + + + + + + + As you can see from the above configuration we have a chain with inner header-enricher element which will further enrich the + content of the Message with the header CREDIT_SCORE and value that will be determined by the call to a + credit service (simple POJO spring bean identified by 'creditBureau' name) and then it will delegate to the Message Router + + Message Router + + + + + + + + + + + There are several implementation of Message Routing pattern available in Spring Integration. Here we are using + router that will determine a list of channels based on evaluating an expression (Spring Expression Language) which will look at + the credit score that was determined is the previous step and will select the list of channels from the Map bean with id 'banks' + whose values are 'premier' or 'secondary' based o the value of credit score. Once the list of Channels is selected, the + Message will be routed to those Channels. + + + Now, one last thing the Loan Broker needs to to is to receive the loan quotes form the banks, aggregate them by consumer + (we don't want to show quotes from one consumer to another), assemble the response based on the consumer's selection criteria + (single best quote or all quotes) and reply back to the consumer. + + Message Aggregator + + + + + + + + + + + + An Aggregator pattern describes an endpoint which groups related Messages into a single + Message. Criteria and rules can be provided to determine an aggregation and correlation strategy. + SI provides several implementations of the Aggregator pattern as well as a convenient name-space based configuration. + + +]]> + + + + Our Loan Broker defines a 'quotesAggregator' bean via the <aggregator> element which provides a default + aggregation and correlation strategy. The default correlation strategy correlates messages based on the $corelationId header + (see Correlation Identifier pattern). What's interesting is that we never provided the value for this header. + It was set earlier by the router automatically, when it generated a separate Message for each Bank channel. + + + Once the Messages are correlated they are released to the actual Aggregator implementation. + Although default Aggregator is provided by SI, its strategy (gather the list of payloads from all + Messages and construct a new Message with this List as payload) does not satisfy our + requirement. The reason is that our consumer might require a single best quote or all quotes. To communicate the consumer's + intention, earlier in the process we set the RESPONSE_TYPE header. Now we have to evaluate this header and return either + all the quotes (the default aggregation strategy would work) or the best quote (the default aggregation strategy will not work + because we have to determine which loan quote is the best). + + + + Obviously selecting the best quote could be based on complex criteria and would influence the complexity of the aggregator implementation and + configuration, but for now we are making it simple. If consumer wants the best quote we will select a quote with the lowest interest + rate. To accomplish that the LoanQuoteAggregator.java will sort all the quotes and return the first one. + The LoanQuote.java implements Comparable which compares quotes based on the rate attribute. + Once the response Message is created it is sent to the default-reply-channel of the Messaging Gateway + (thus the consumer) which started the process. Our consumer got the Loan Quote! + + Conclusion + + As you can see a rather complex process was assembled based on POJO (read existing, legacy), light weight, embeddable messaging + framework (Sprig Integration) with a loosely coupled programming model intended to simplify integration of heterogeneous systems + without requiring a heavy-weight ESB-like engine or proprietary development and deployment environment, becouse as a developer you + should not be porting your Swing or console-based application to an ESB-like server or implementing proprietary interfaces just + because you have an integration concern. + + + This and other samples in this section are build on top of Enterprise Integration Patterns that meant to describe "building blocks" + for YOUR solution but not to be solutions in of themselves. Integration concerns exist in all types of applications (server based and not) + and should not require change in design, testing and deployment strategy if such applications need to integrate with one another. +
+ + + +
The Cafe Sample - In this section, we will review a sample application that is included in the Spring Integration - distribution. This sample is inspired by one of the samples featured in Gregor Hohpe's - Ramblings. + In this section, we will review a Cafe sample application that is included in the + Spring Integration samples. This sample is inspired by another sample featured in Gregor + Hohpe's Ramblings. The domain is that of a Cafe, and the basic flow is depicted in the following diagram: @@ -163,11 +401,11 @@ That includes Samples, so if you can't find what you are looking for let us know - - +