diff --git a/docs/src/reference/docbook/content-enrichment.xml b/docs/src/reference/docbook/content-enrichment.xml index 0d35e186f5..c3429b0a8d 100644 --- a/docs/src/reference/docbook/content-enrichment.xml +++ b/docs/src/reference/docbook/content-enrichment.xml @@ -16,17 +16,17 @@ The Spring Integration Core module includes 2 enrichers: - Header Enricher - (Generic) Enricher + Header Enricher + Payload Enricher Furthermore, several Adapter specific Header Enrichers are included as well: - XPath Header Enricher (XML Module) - Email Header Enricher (Mail Module) - XMPP Header Enricher (XMPP Module) + XPath Header Enricher (XML Module) + Mail Header Enricher (Mail Module) + XMPP Header Enricher (XMPP Module) Please go to the adapter specific sections of this reference manual @@ -147,22 +147,309 @@ -
- (Generic) Enricher - +
+ Payload Enricher + + In certain situations the Header Enricher, as discussed above, may + not be sufficient and payloads themselves may have to be enriched + with additional information. For example, order messages that enter + the Spring Integration messaging system have to look up the order's + customer based on the provided customer number and then enrich the original + payload with that information. + + + Since Spring Integration 2.1, the Payload Enricher is provided. A + Payload Enricher defines an endpoint that passes a + Message to the exposed request channel and then + expects a reply message. The reply message then becomes the root object + for evaluation of expressions to enrich the target payload. + + + The Payload Enricher provides full XML namespace support via the enricher + element. In order to send request messages, the payload enricher has a + request-channel attribute that allows you to dispatch + messages to a request channel. + + + Basically by defining the request channel, the Payload Enricher acts + as a Gateway, waiting for the message that were sent to the request + channel to return, and the Enricher then augments the message's payload with + the data provided by the reply message. + + + When sending messages to the request channel you also have the option + to only send a subset of the original payload using the + request-payload-expression attribute. + + + The enriching of payloads is configured through SpEL expressions, + providing users with a maximum degree of flexibility. Therefore, users + are not only able to enrich payloads with direct values from the reply channel's + Message, but they can use SpEL + expressions to extract a subset from that Message, only, or to apply + addtional inline transformations, allowing them to further manipulate + the data. + + + If you only need to enrich payloads with static values, you don't have + to provide the request-channel attribute. + + + Enrichers are a variant of Transformers and in many cases you could + use a Payload Enricher or a generic Transformer implementation to add + additional data to your messages payloads. Thus, familiarize yourself + with all transformation-capable components that are provided by Spring + Integration and carefully select the implementation that semantically + fits your business case best. + - - - +
+ Configuration + + + Below, please find an overview of all available configuration options that + are available for the payload enricher: + + + ]]> ]]> ]]> ]]> + + + + + + Channel to which a Message will be sent to get the data to use for enrichment. + Optional. + + + + + Lifecycle attribute signaling if this component should be + started during Application Context startup. Defaults to true. + Optional. + + + + + Id of the underlying bean definition, which is either + an EventDrivenConsumer or a + PollingConsumer. + Optional. + + + + + Specifies the order for invocation when this endpoint is + connected as a subscriber to a channel. This is particularly + relevant when that channel is using a "failover" dispatching + strategy. It has no effect when this endpoint itself is a + Polling Consumer for a channel with a queue. + Optional. + + + + + Identifies the Message channel where a Message will + be sent after it is being processed by this endpoint. + Optional. + + + + + By default the original message's payload will be used as + payload that will be send to the request-channel. + By specifying a SpEL expression as value for the + request-payload-expression attribute, a + subset of the original payload, a header value or any other + resolvable SpEL expression can be used as the basis for the + payload, that will be sent to the request-channel. + + + For the Expression evaluation the full message is available + as the 'root object'. + + + For instance the following SpEL expressions (among others) + are possible: + + + payload.foo + headers.foobar + new java.util.Date() + 'foo' + 'bar' + + + If more sophisticated logic is required (e.g. changing the + message headers etc.) please use additional downstream transformers. + Optional. + + + + + Channel where a reply Message is expected. This is optional; typically the auto-generated + temporary reply channel is sufficient. + Optional. + + + + + Maximum amount of time in milliseconds to wait when + sending a message to the channel, if such channel may block. + + + For example, a Queue Channel can block until space is + available, if its maximum capacity has been reached. Internally + the send timeout is set on the MessagingTemplate + and ultimately applied when invoking the send operation on the + MessageChannel. + + + By default the send timeout is set to '-1', which may cause + the send operation on the MessageChannel, + depending on the implementation, to block indefinitely. + Optional. + + + + + Boolean value indicating whether any payload that implements + Cloneable should be cloned + prior to sending the Message to the request chanenl for + acquiring the enriching data. The cloned version would be + used as the target payload for the ultimate reply. + Default is false. + Optional. + + + + + Allows you to configure a Message Poller if this endpoint + is a Polling Consumer. + Optional. + + + + + Each property sub-element provides the + name of a property (via the mandatory name + attribute). That property should be settable on the + target payload instance. Exactly one of the value + or expression attributes must be provided + as well. The former for a literal value to set, and the + latter for a SpEL expression to be evaluated. The root + object of the evaluation context is the Message that was + returned from the flow initiated by this enricher. + + + + + +
+ +
+ Examples + + + Below, please find several examples of using a Payload Enricher + in various situations. + + + + In the following example, a User object is passed + as the payload of the Message. The + User has several properties but only the + username is set initially. The Enricher's + request-channel attribute below is configured to + pass the User on to the findUserServiceChannel. + + + Through the implicitly set reply-channel a + User object is returned and using the + property sub-element, properties from the reply are + extracted and used to enrich the original payload. + + + + + +]]> + + + The code samples shown here, are part of the Spring + Integration Samples project. Please feel free to + check it out at: + + + + + + How do I pass only a subset of data to the request channel? + + Using a request-payload-expression attribute + a single property of the payload can be passed on to the request + channel instead of the full message. In the example below on the + username property is passed on to the request channel. Keep in mind, + that alwhough only the username is passed on, the resulting message + send to the request channel will contain the full set of + MessageHeaders. + + + + + +]]> + + How can I enrich payloads that consist of Collection data? + + In the following example, instead of a User object, + a Map is passed in. The + Map contains the username under the map + key username. Only the username is passed on + to the request channel. The reply contains a full User object, which + is ultimately added to the Map under the + user key. + + + + +]]> + + How can I enrich payloads with static information without using a request channel? + + Here is an example that does not use a request channel at all, + but solely enriches the message's payload with static values. But please + be aware that the word 'static' is used loosly here. You can still use + SpEL expressions for setting those values. + + + + + + + +]]> + +
+
diff --git a/spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.1.xsd b/spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.1.xsd index eaf4bbae3b..9536a2945e 100644 --- a/spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.1.xsd +++ b/spring-integration-core/src/main/resources/org/springframework/integration/config/xml/spring-integration-2.1.xsd @@ -986,7 +986,7 @@ endpoint itself is a Polling Consumer for a channel with a queue. Defines an endpoint that passes a Message to its request-channel and then expects a reply Message. The reply Message then becomes - the root object for evaluation of expressions to enriche the + the root object for evaluation of expressions to enrich the target payload. @@ -1068,7 +1068,7 @@ endpoint itself is a Polling Consumer for a channel with a queue. as value for the 'request-payload-expression' attribute, a subset of the original payload, a header value or any other resolvable SpEL expression can be used as the basis for the payload, - that will be send to the request-channel. + that will be sent to the request-channel. For the Expression evaluation the full message is available as the 'root object'.