From d8c1049ba8d2c96cdf87462b2b3b6b80e9f8d12c Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Mon, 27 Oct 2008 22:29:26 +0000 Subject: [PATCH] Updated namespaces appendix --- .../src/namespaces.xml | 179 ++++++++---------- 1 file changed, 78 insertions(+), 101 deletions(-) diff --git a/spring-integration-reference/src/namespaces.xml b/spring-integration-reference/src/namespaces.xml index 045d6ed0bf..1b66bf8ff9 100644 --- a/spring-integration-reference/src/namespaces.xml +++ b/spring-integration-reference/src/namespaces.xml @@ -18,7 +18,7 @@ Enterprise Integration Patterns. - To enable Spring Integration's namespace support within your Spring configuration files, add the following + To enable Spring Integration's core namespace support within your Spring configuration files, add the following namespace reference and schema mapping in your top-level 'beans' element: + + Many other namespaces are provided within the Spring Integration distribution. In fact, each adapter type (JMS, + File, etc.) that provides namespace support defines its elements within a separate schema. In order to use these + elements, simply add the necessary namespaces with an "xmlns" entry and the corresponding "schemaLocation" mapping. + For example, the following root element shows several of these namespace declarations: + + + ... +]]> + The reference manual provides specific examples of the various elements in their corresponding chapters. Here, the + main thing to recognize is the consistency of the naming for each namespace URI and schema location. +
Configuring Message Endpoints @@ -227,15 +260,11 @@ ]]> - Likewise, here is an example of a JMS target that is registered within a 'channel-adapter' and whose Messages - will be received from the "exampleChannel" that is polled every 500 milliseconds. - - - + + + + - -]]> - Any Channel Adapter can be created without a "channel" reference in which case it will implicitly create an instance of DirectChannel. The created channel's name will match the "id" attribute @@ -243,40 +272,39 @@
-
- Enabling Annotation-Driven Configuration - - The next section will describe Spring Integration's support for annotation-driven configuration. To enable - those features, add this single element to the XML-based configuration: - <annotation-driven/> - -
+ +
Annotations In addition to the XML namespace support for configuring Message Endpoints, it is also possible to use - annotations. The class-level @MessageEndpoint annotation indicates that the - annotated class is capable of being registered as an endpoint, and the method-level - @Handler annotation indicates that the annotated method is capable of handling - a message. - @MessageEndpoint(input="fooChannel") + annotations. First, Spring Integration provides the class-level @MessageEndpoint + as a stereotype annotation meaning that is itself annotated with Spring's @Component + annotation and therefore is recognized automatically as a bean definition when using Spring component-scanning. + + + Even more importantly are the various Method-level annotations that indicate the annotated method is capable of + handling a message. The following example demonstrates both: + @MessageEndpoint public class FooService { - @Handler + @ServiceActivator public void processMessage(Message message) { ... } } - The @MessageEndpoint is not required. If you want to configure a POJO reference from the "ref" attribute - of a <service-activator/> element, it is sufficient to provide the @Handler method annotation. As long - as the "annotation-driven" support is enabled, a Spring-managed object with that method annotation (or the - others which are described below) will be post-processed such that it can be used as a reference from an - XML-configured endpoint. + Exactly what it means for the method to "handle" the Message depends on the particular annotation. The following + are available with Spring Integration, and the behavior of each is described in its own chapter or section within + this reference: @Transformer, @Router, @Splitter, @Aggregator, @ServiceActivator, and @ChannelAdapter. + + The @MessageEndpoint is not required. If you want to configure a POJO reference from the "ref" attribute + of a <service-activator/> element, it is sufficient to provide the method-level annotations. + In most cases, the annotated handler method should not require the Message type as its parameter. Instead, the method parameter type can match the message's payload type. @@ -291,85 +319,34 @@ public class FooService { When the method parameter should be mapped from a value in the MessageHeader, another - option is to use the parameter-level @Header annotation. - @MessageEndpoint(input="fooChannel") -public class FooService { - - @Handler - public void bar(@Header("foo") Foo foo) { - ... - } - -} - - - As described in the previous section, when the handler method returns a non-null value, the endpoint will - attempt to send a reply. This is consistent across both configuration options (namespace and annotations) in that - the the endpoint's output channel will be used if available, and the message header's RETURN_ADDRESS value will be - the fallback. To configure the output channel for an annotation-driven endpoint, provide the 'output' - attribute on the @MessageEndpoint. - @MessageEndpoint(input="exampleChannel", output="replyChannel") - - - Just as the 'poller' sub-element and its 'period' attribute can be provided for a namespace-based - endpoint, the @Poller annotation can be provided with the - @MessageEndpoint annotation. - @MessageEndpoint(input="exampleChannel") -@Poller(period=3000) -public class FooService { - ... -} - Likewise, @Concurrency provides an annotation-based equivalent of the - <pool-executor/> element: - @MessageEndpoint(input="fooChannel") -@Concurrency(coreSize=5, maxSize=20) -public class FooService { - - @Handler - public void bar(Foo foo) { - ... - } - -} - - - Several additional annotations are supported, and three of these act as a special form of handler method: - @Router, @Splitter and - @Aggregator. As with the @Handler annotation, - methods annotated with these annotations can either accept the Message itself, the + option is to use the parameter-level @Header annotation. In general, methods + annotated with the Spring Integration annotations can either accept the Message itself, the message payload, or a header value (with @Header) as the parameter. In fact, the method can accept a combination, such as: - someMethod(String payload, @Header("x") int valueX, @Header("y") int valueY); - - - The @Aggregator annotation may be used on a method that accepts a collection - of Messages or Message payload types and whose return value is a single Message or single Object that will - be used as the payload of a Message. - aggregateMessages(List> messages) { ... } + public class FooService { -@Aggregator -public Order aggregateOrder(List items) { ... }]]> - - - Finally, the @Publisher is an annotation that triggers the creation of a Spring - AOP Proxy such that the return value, exception, or method invcation arguments can be sent to a Message Channel. - For example, each time the following method is invoked, its return value will be sent to the "fooChannel": - - The return value is published by default, but you can also configure the payload type: - @Publisher(channel="testChannel", payloadType=MessagePublishingInterceptor.PayloadType.ARGUMENTS) -public void publishArguments(String s, Integer n) { - ... -} + @ServiceActivator + public void bar(String payload, @Header("x") int valueX, @Header("y") int valueY) { + ... + } + +} + There is also a @Headers annotation that provides all of the Message headers as a Map: + public class FooService { + + @ServiceActivator + public void bar(String payload, @Headers Map<String, Object> headerMap) { + ... + } -@Publisher(channel="testChannel", payloadType=MessagePublishingInterceptor.PayloadType.EXCEPTION) -public void publishException() { - throw new RuntimeException("oops!"); } + + For several of these annotations, when a Message-handling method returns a non-null value, the endpoint will + attempt to send a reply. This is consistent across both configuration options (namespace and annotations) in that + the such an endpoint's output channel will be used if available, and the message header's REPLY_CHANNEL value + will be the fallback. +
\ No newline at end of file