From 6e3428536163ee8155d9a8670c6c0913b4de78e6 Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Sat, 4 Jul 2009 17:18:24 +0000 Subject: [PATCH] INT-676 added examples for wire tap, to-string and serialization transformers --- spring-integration-reference/src/channel.xml | 49 ++++++++++++--- .../src/transformer.xml | 62 ++++++++++++++----- 2 files changed, 86 insertions(+), 25 deletions(-) diff --git a/spring-integration-reference/src/channel.xml b/spring-integration-reference/src/channel.xml index 5fc3044fa4..7de93029b7 100644 --- a/spring-integration-reference/src/channel.xml +++ b/spring-integration-reference/src/channel.xml @@ -258,6 +258,11 @@ the preReceive(..) and postReceive(..) interceptor methods are only invoked when the interceptor is applied to a PollableChannel. + Spring Integration also provides an implementation of the + Wire Tap pattern. + It is a simple interceptor that sends the Message to another channel without otherwise altering the + existing flow. It can be very useful for debugging and monitoring. An example is shown in + . Because it is rarely necessary to implement all of the interceptor methods, a @@ -450,19 +455,45 @@ public Message receive(final PollableChannel channel) { ... }]]>]]> - - Message channels may also have interceptors as described in . One or - more <interceptor> elements can be added as sub-elements of <channel> (or the more specific element - types). Provide the "ref" attribute to reference any Spring-managed object that implements the - ChannelInterceptor interface: - + +
+ Channel Interceptor Configuration + + Message channels may also have interceptors as described in . The + <interceptors> sub-element can be added within <channel> (or the more specific element + types). Provide the "ref" attribute to reference any Spring-managed object that implements the + ChannelInterceptor interface: + ]]> ]]>]]> - In general, it is a good idea to define the interceptor implementations in a separate location since they - usually provide common behavior that can be reused across multiple channels. - + In general, it is a good idea to define the interceptor implementations in a separate location since they + usually provide common behavior that can be reused across multiple channels. + +
+ +
+ Wire Tap + + As mentioned above, Spring Integration provides a simple Wire Tap interceptor out of + the box. You can configure a Wire Tap on any channel within an 'interceptors' element. + This is especially useful for debugging, and can be used in conjunction with Spring Integration's logging + Channel Adapter as follows: + + + + + + ]]> + + The 'logging-channel-adapter' also accepts a boolean attribute: 'log-full-message'. + That is false by default so that only the payload is logged. Setting that to + true enables logging of all headers in addition to the payload. + + +
+ If namespace support is enabled, there are also two special channels defined within the context by default: diff --git a/spring-integration-reference/src/transformer.xml b/spring-integration-reference/src/transformer.xml index e4880c3c6a..4210cd3ec0 100644 --- a/spring-integration-reference/src/transformer.xml +++ b/spring-integration-reference/src/transformer.xml @@ -40,33 +40,63 @@ ]]> - Using a "ref" attribute is generally recommended if custom transformer handler implementation can be reused in other <transformer> definitions. However -if custom transformer handler implementation has to be scoped to a concrete definition of the <transformer>, starting with v1.0.3, Spring Integration supports -inner bean definitions for custom transformer handlers within the <transformer> element: + Using a "ref" attribute is generally recommended if the custom transformer handler implementation can be reused in + other <transformer> definitions. However if the custom transformer handler implementation should + be scoped to a single definition of the <transformer>, you can define an inner bean definition: ]]> - - Using both "ref" attribute and inner handler definition in the same <transformer> configuration - is not allowed, as it creates an ambiguous condition and will result in Exception being thrown - + + Using both the "ref" attribute and an inner handler definition in the same <transformer> + configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown. + - The method that is used for transformation may expect either the Message type or - the payload type of inbound Messages. The return value of the method can be any type. If the return value is - itself a Message, that will be passed along to the transformer's output channel. - If the return value is null, then no reply Message will be sent (effectively the same - behavior as a Message Filter). Otherwise, the return value will be sent as the payload of a Message. + the payload type of inbound Messages. It may also accept Message header values either individually or as a full + map by using the @Header and @Headers parameter annotations respectively. The return value of the method can be + any type. If the return value is itself a Message, that will be passed along to + the transformer's output channel. If the return type is a Map, and the original Message payload was + not a Map, the entries in that Map will be added to the Message headers of the original + Message (the keys must be Strings). If the return value is null, then no reply Message will + be sent (effectively the same behavior as a Message Filter returning false). Otherwise, the return value will be + sent as the payload of an outbound reply Message. - Using both "ref" attribute and inner handler definition in the same <router> configuration is not - allowed, as it creates an ambiguous condition and will result in Exception being thrown + + Using both the "ref" attribute and an inner handler definition in the same <transformer> + configuration is not allowed, as it creates an ambiguous condition and will result in an Exception being thrown. + - + + There are a also a few Transformer implementations available out of the box. Because, it is fairly common + to use the toString() representation of an Object, Spring Integration provides an + ObjectToStringTransformer whose output is a Message with a String payload. That String + is the result of invoking the toString operation on the inbound Message's payload. + ]]> + A potential example for this would be sending some arbitrary object to the 'outbound-channel-adapter' in the + file namespace. Whereas that Channel Adapter only supports String, byte-array, or + java.io.File payloads by default, adding this transformer immediately before the + adapter will handle the necessary conversion. Of course, that works fine as long as the result of the + toString() call is what you want to be written to the File. Otherwise, you can + just provide a custom POJO-based Transformer via the generic 'transformer' element shown previously. + + When debugging, this transformer is not typically necessary since the 'logging-channel-adapter' is capable + of logging the Message payload. Refer to for more detail. + + + + If you need to serialize an Object to a byte array or deserialize a byte array back into an Object, + Spring Integration provides symmetrical serialization transformers. + + + ]]> +
@@ -81,7 +111,7 @@ Order generateOrder(String productId) { } - Transformer methods may also accept the @Header and @Headers annotations that is documented in section + Transformer methods may also accept the @Header and @Headers annotations that is documented in @Transformer Order generateOrder(String productId, @Header("customerName") String customer) { return new Order(productId, customer);