From f236671902823e31d09139c5a6b6b967a253c79c Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Tue, 21 Oct 2008 02:31:10 +0000 Subject: [PATCH] Moved channel, router and splitter coverage from old configuration chapter --- spring-integration-reference/src/channel.xml | 105 +++++++++ .../src/{routing.xml => jms.xml} | 5 +- .../src/namespaces.xml | 206 ++---------------- spring-integration-reference/src/router.xml | 37 ++++ spring-integration-reference/src/splitter.xml | 22 ++ .../src/splitting.xml | 15 -- .../src/spring-integration-reference.xml | 5 +- 7 files changed, 187 insertions(+), 208 deletions(-) rename spring-integration-reference/src/{routing.xml => jms.xml} (77%) create mode 100644 spring-integration-reference/src/router.xml create mode 100644 spring-integration-reference/src/splitter.xml delete mode 100644 spring-integration-reference/src/splitting.xml diff --git a/spring-integration-reference/src/channel.xml b/spring-integration-reference/src/channel.xml index 4f105f6de4..dd19db8dd8 100644 --- a/spring-integration-reference/src/channel.xml +++ b/spring-integration-reference/src/channel.xml @@ -247,4 +247,109 @@ public Message sendAndReceive(final Message request, final MessageChannel public Message receive(final PollableChannel channel) { ... }]]> + +
+ Configuring Message Channels + + To create a Message Channel instance, you can use the 'channel' element: + <channel id="exampleChannel"/> + + + The default channel type is Point to Point. To create a + Publish Subscribe channel, use the "publish-subscribe-channel" element: + <publish-subscribe-channel id="exampleChannel"/> + + + To create a Datatype Channel that only + accepts messages containing a certain payload type, provide the fully-qualified class name in the + channel element's datatype attribute: + ]]> + Note that the type check passes for any type that is assignable to the channel's + datatype. In other words, the "numberChannel" above would accept messages whose payload is + java.lang.Integer or java.lang.Double. Multiple types can be + provided as a comma-delimited list: + ]]> + + + When using the "channel" element without any sub-elements, it will create a DirectChannel + instance (a SubscribableChannel). + + + However, you can also provide a variety of "queue" sub-elements to create the channel types (as described in + ). Examples of each are shown below. + +
+ DirectChannel Configuration + + As mentioned above, DirectChannel is the default type. + ]]> + +
+
+ QueueChannel Configuration + + To create a QueueChannel, use the "queue" sub-element. + You must specify the channel's capacity: + <channel id="exampleChannel"> + <queue capacity="25"/> +</channel> + +
+
+ PublishSubscribeChannel Configuration + + To create a PublishSubscribeChannel, use the "publish-subscribe-channel" element. + When using this element, you can also specify the "task-executor" used for publishing + Messages (if none is specified it simply publishes in the sender's thread): + <publish-subscribe-channel id="exampleChannel" task-executor="someTaskExecutor"/> + +
+
+ PriorityChannel Configuration + + To create a PriorityChannel, use the "priority-queue" sub-element: + + +]]> + By default, the channel will consult the MessagePriority header of the + message. However, a custom Comparator reference may be + provided instead. Also, note that the PriorityChannel (like the other types) + does support the "datatype" attribute. As with the QueueChannel, it also supports a "capacity" attribute. + The following example demonstrates all of these: + + + +]]> + +
+
+ RendezvousChannel Configuration + + The RendezvousChannel does not provide any additional configuration options. + + + +]]> + +
+
+ ThreadLocalChannel Configuration + + The ThreadLocalChannel does not provide any additional configuration options. + ]]> + +
+ + 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: + + ]]>]]>]]> + 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. + +
\ No newline at end of file diff --git a/spring-integration-reference/src/routing.xml b/spring-integration-reference/src/jms.xml similarity index 77% rename from spring-integration-reference/src/routing.xml rename to spring-integration-reference/src/jms.xml index 0f946343bc..aa8140daf8 100644 --- a/spring-integration-reference/src/routing.xml +++ b/spring-integration-reference/src/jms.xml @@ -2,11 +2,10 @@ - Message Routing + JMS Support
- Introduction - + diff --git a/spring-integration-reference/src/namespaces.xml b/spring-integration-reference/src/namespaces.xml index 65b5e584ee..9c19eb2392 100644 --- a/spring-integration-reference/src/namespaces.xml +++ b/spring-integration-reference/src/namespaces.xml @@ -1,11 +1,8 @@ - - Configuration - -
- Introduction - + + Namespace Support + Spring Integration offers a number of configuration options. Which option you choose depends upon your particular needs and at what level you prefer to work. As with the Spring framework in general, it is also possible to mix and match the various techniques according to the particular problem at hand. For example, you may choose the @@ -14,17 +11,13 @@ match the names of annotations, and the attributes of those XML elements will match the names of annotation properties. Direct usage of the API is of course always an option, but we expect that most users will choose one of the higher-level options, or a combination of the namespace-based and annotation-driven configuration. - -
- -
- Namespace Support - + + Spring Integration components can be configured with XML elements that map directly to the terminology and concepts of enterprise integration. In many cases, the element names match those of the Enterprise Integration Patterns. - - + + To enable Spring Integration's namespace support within your Spring configuration files, add the following namespace reference and schema mapping in your top-level 'beans' element: http://www.springframework.org/schema/integration http://www.springframework.org/schema/integration/spring-integration-1.0.xsd"> - - + + You can choose any name after "xmlns:"; integration is used here for clarity, but you might prefer a shorter abbreviation. Of course if you are using an XML-editor or IDE support, then the availability of auto-completion may convince you to keep the longer name for clarity. Alternatively, you can create configuration @@ -47,8 +40,8 @@ http://www.springframework.org/schema/beans/spring-beans-2.5.xsd http://www.springframework.org/schema/integration http://www.springframework.org/schema/integration/spring-integration-1.0.xsd">]]> - - + + When using this alternative, no prefix is necessary for the Spring Integration elements. On the other hand, if you want to define a generic Spring "bean" within the same configuration file, then a prefix would be required for the bean element (<beans:bean ... />). Since it is generally a good idea to modularize the @@ -56,109 +49,9 @@ use the latter approach in the integration-focused configuration files, since generic beans are seldom necessary within those same files. For purposes of this documentation, we will assume the "integration" namespace is primary. - + -
- Configuring Message Channels - - To create a Message Channel instance, you can use the generic 'channel' element: - <channel id="exampleChannel"/> - - - The default channel type is Point to Point. To create a - Publish Subscribe channel, use the "publish-subscribe-channel" element: - <publish-subscribe-channel id="exampleChannel"/> - - - To create a Datatype Channel that only - accepts messages containing a certain payload type, provide the fully-qualified class name in the - channel element's datatype attribute: - ]]> - Note that the type check passes for any type that is assignable to the channel's - datatype. In other words, the "numberChannel" above would accept messages whose payload is - java.lang.Integer or java.lang.Double. Multiple types can be - provided as a comma-delimited list: - ]]> - - - When using the "channel" element, the creation of the channel instances will be deferred to the ChannelFactory - bean whose name is "channelFactory" if defined within the ApplicationContext. If no such bean is defined, the default factory will - be used. The default implementation is QueueChannelFactory. - - - It is also possible to use more specific elements for the various channel types (as described in - ). Depending on the channel, these may provide additional configuration - options. Examples of each are shown below. - -
- The <queue-channel/> element - - To create a QueueChannel, use the "queue-channel" element. - By using this element, you can also specify the channel's capacity: - <queue-channel id="exampleChannel" capacity="25"/> - -
-
- The <publish-subscribe-channel/> element - - To create a PublishSubscribeChannel, use the "publish-subscribe-channel" element. - When using this element, you can also specify the "task-executor" used for publishing - Messages (if none is specified it simply publishes in the sender's thread): - <publish-subscribe-channel id="exampleChannel" task-executor="someTaskExecutor"/> - -
-
- The <priority-channel/> element - - To create a PriorityChannel, use the "priority-channel" element: - ]]> - By default, the channel will consult the MessagePriority header of the - message. However, a custom Comparator reference may be - provided instead. Also, note that the PriorityChannel (like the other types) - does support the "datatype" attribute. As with the "queue-channel", it also supports a "capacity" attribute. - The following example demonstrates all of these: - -]]> - -
-
- The <rendezvous-channel/> element - - The RendezvousChannel does not provide any additional configuration options. - ]]> - -
-
- The <direct-channel/> element - - The DirectChannel does not provide any additional configuration options. - ]]> - -
-
- The <thread-local-channel/> element - - The ThreadLocalChannel does not provide any additional configuration options. - ]]> - -
- - 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: - - ]]>]]>]]> - 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. - -
- -
+
Configuring Message Endpoints Each of the endpoint types (channel-adapter, service-activator, etc) has its own element in the namespace. @@ -234,33 +127,6 @@ ]]> - - Another important configuration option for message endpoints is the inclusion of - EndpointInterceptors. The interface is defined as follows: - preHandle(Message requestMessage); - - Message aroundHandle(Message requestMessage, MessageHandler handler); - - Message postHandle(Message replyMessage); - -}]]> - There is also an EndpointInterceptorAdapter that provides no-op methods for convenience - when subclassing. Within an endpoint configuration, interceptors can be added within - the <interceptors> sub-element. It accepts either "ref" elements or inner "beans": - - - - - - -]]> - Spring Integration also provides transaction support for the pollers so that each receive-and-forward operation can be performed as an atomic unit-of-work. To configure transactions for a poller, simply @@ -303,7 +169,7 @@
-
+
Configuring the Message Bus The Message Bus plays a central role, but its configuration is quite simple since it is primarily concerned @@ -345,7 +211,7 @@
-
+
Configuring Adapters The most convenient way to configure Source and Target adapters is by using the namespace support. The @@ -400,7 +266,7 @@
-
+
Enabling Annotation-Driven Configuration The next section will describe Spring Integration's support for annotation-driven configuration. To enable @@ -408,7 +274,7 @@ <annotation-driven/>
-
+
Annotations @@ -498,43 +364,6 @@ public class FooService { such as: someMethod(String payload, @Header("x") int valueX, @Header("y") int valueY); - - When using the @Router annotation, the annotated method can return either the - MessageChannel or String type. In the case of the latter, - the endpoint will resolve the channel name as it does for the default output. Additionally, the method can return - either a single value or a collection. When a collection is returned, the reply message will be sent to multiple - channels. To summarize, the following method signatures are all valid. - @Router -public MessageChannel route(Message message) {...} - -@Router -public List<MessageChannel> route(Message message) {...} - -@Router -public String route(Foo payload) {...} - -@Router -public List<String> route(Foo payload) {...} - - - In addition to payload-based routing, a common requirement is to route based on metadata available within the - message header as either a property or attribute. Rather than requiring use of the - Message type as the method parameter, the @Router - annotation may also use the same @Header parameter annotation that was introduced above. - @Router -public List<String> route(@Header("orderStatus") OrderStatus status) - - - The @Splitter annotation is also applicable to methods that expect either the - Message type or the message payload type, and the return values of the method - should be a collection of any type. If the returned values are not actual Message - objects, then each of them will be sent as the payload of a message. Those messages will be sent to the output - channel as designated for the endpoint on which the @Splitter is defined. - @Splitter -List<LineItem> extractItems(Order order) { - return order.getItems() -} - 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 @@ -565,4 +394,5 @@ public void publishException() { }
+ \ No newline at end of file diff --git a/spring-integration-reference/src/router.xml b/spring-integration-reference/src/router.xml new file mode 100644 index 0000000000..3a996619ac --- /dev/null +++ b/spring-integration-reference/src/router.xml @@ -0,0 +1,37 @@ + + + + Message Routing + +
+ The @Router Annotation + + When using the @Router annotation, the annotated method can return either the + MessageChannel or String type. In the case of the latter, + the endpoint will resolve the channel name as it does for the default output. Additionally, the method can return + either a single value or a collection. When a collection is returned, the reply message will be sent to multiple + channels. To summarize, the following method signatures are all valid. + @Router +public MessageChannel route(Message message) {...} + +@Router +public List<MessageChannel> route(Message message) {...} + +@Router +public String route(Foo payload) {...} + +@Router +public List<String> route(Foo payload) {...} + + + In addition to payload-based routing, a common requirement is to route based on metadata available within the + message header as either a property or attribute. Rather than requiring use of the + Message type as the method parameter, the @Router + annotation may also use the same @Header parameter annotation that was introduced above. + @Router +public List<String> route(@Header("orderStatus") OrderStatus status) + +
+ + \ No newline at end of file diff --git a/spring-integration-reference/src/splitter.xml b/spring-integration-reference/src/splitter.xml new file mode 100644 index 0000000000..ec5a356eb5 --- /dev/null +++ b/spring-integration-reference/src/splitter.xml @@ -0,0 +1,22 @@ + + + + Message Splitter + +
+ The @Splitter Annotation + + The @Splitter annotation is also applicable to methods that expect either the + Message type or the message payload type, and the return values of the method + should be a collection of any type. If the returned values are not actual Message + objects, then each of them will be sent as the payload of a message. Those messages will be sent to the output + channel as designated for the endpoint on which the @Splitter is defined. + @Splitter +List<LineItem> extractItems(Order order) { + return order.getItems() +} + +
+ + \ No newline at end of file diff --git a/spring-integration-reference/src/splitting.xml b/spring-integration-reference/src/splitting.xml deleted file mode 100644 index e86d196135..0000000000 --- a/spring-integration-reference/src/splitting.xml +++ /dev/null @@ -1,15 +0,0 @@ - - - - Message Splitting - -
- Introduction - - - - -
- - \ No newline at end of file diff --git a/spring-integration-reference/src/spring-integration-reference.xml b/spring-integration-reference/src/spring-integration-reference.xml index 62be9966d5..3ebc8f2261 100644 --- a/spring-integration-reference/src/spring-integration-reference.xml +++ b/spring-integration-reference/src/spring-integration-reference.xml @@ -44,12 +44,13 @@ - + - + +