diff --git a/spring-integration-reference/images/channel.png b/spring-integration-reference/images/channel.png index 310245e8d5..25e3458dca 100644 Binary files a/spring-integration-reference/images/channel.png and b/spring-integration-reference/images/channel.png differ diff --git a/spring-integration-reference/images/handler-endpoint.png b/spring-integration-reference/images/handler-endpoint.png index 89b4fbb3f0..a34526e48e 100644 Binary files a/spring-integration-reference/images/handler-endpoint.png and b/spring-integration-reference/images/handler-endpoint.png differ diff --git a/spring-integration-reference/images/handler.png b/spring-integration-reference/images/handler.png index 89f9b90c2d..f1398d5d36 100644 Binary files a/spring-integration-reference/images/handler.png and b/spring-integration-reference/images/handler.png differ diff --git a/spring-integration-reference/images/message.png b/spring-integration-reference/images/message.png index 26380df863..8c08501d80 100644 Binary files a/spring-integration-reference/images/message.png and b/spring-integration-reference/images/message.png differ diff --git a/spring-integration-reference/images/source-endpoint.png b/spring-integration-reference/images/source-endpoint.png index 39777d0704..1617a6c5d9 100644 Binary files a/spring-integration-reference/images/source-endpoint.png and b/spring-integration-reference/images/source-endpoint.png differ diff --git a/spring-integration-reference/images/source.png b/spring-integration-reference/images/source.png index ea28542f39..bec59cf7b3 100644 Binary files a/spring-integration-reference/images/source.png and b/spring-integration-reference/images/source.png differ diff --git a/spring-integration-reference/images/target-endpoint.png b/spring-integration-reference/images/target-endpoint.png index 39e2c34a3f..7a9e1613ac 100644 Binary files a/spring-integration-reference/images/target-endpoint.png and b/spring-integration-reference/images/target-endpoint.png differ diff --git a/spring-integration-reference/images/target.png b/spring-integration-reference/images/target.png index 02d7e5ca9f..80362dac21 100644 Binary files a/spring-integration-reference/images/target.png and b/spring-integration-reference/images/target.png differ diff --git a/spring-integration-reference/src/adapters.xml b/spring-integration-reference/src/adapters.xml index 90f790bd46..a89f63f528 100644 --- a/spring-integration-reference/src/adapters.xml +++ b/spring-integration-reference/src/adapters.xml @@ -1,7 +1,7 @@ - Channel Adapters + Adapters
Introduction diff --git a/spring-integration-reference/src/appendix.xml b/spring-integration-reference/src/appendix.xml new file mode 100644 index 0000000000..9865fe88a9 --- /dev/null +++ b/spring-integration-reference/src/appendix.xml @@ -0,0 +1,25 @@ + + + + Appendix + +
+ Spring Integration XML Schema Overview +
+ Spring Integration Core + + +
+
+ Spring Integration Adapters + + +
+
+ Spring Integration Web Services Support + + +
+
+ + \ No newline at end of file diff --git a/spring-integration-reference/src/core-api.xml b/spring-integration-reference/src/core-api.xml index 4592e40aa6..30b6b1fabf 100644 --- a/spring-integration-reference/src/core-api.xml +++ b/spring-integration-reference/src/core-api.xml @@ -102,6 +102,48 @@ new GenericMessage<T>(T payload, MessageHeader headerToCopy)
+
+ Source + + The Source interface defines a single method for receiving + Message objects. + public interface Source<T> { + Message<T> receive(); +} + Spring Integration also provides a MethodInvokingSource implementation that serves as an + adapter for invoking any arbitrary method on a plain Object (i.e. there is no need to implement an interface). + To use the MethodInvokingSource, provide the Object reference and the method name. + MethodInvokingSource source = new MethodInvokingSource(); +source.setObject(new SourceObject()); +source.setMethod("sourceMethod"); +Message<?> result = source.receive(); + It is generally more common to configure a MethodInvokingSource in XML by providing a + bean reference. + ]]> + +
+ +
+ Target + + The Target interface defines a single method for sending + Message objects. + public interface Target { + boolean send(Message<?> message); +} + As with the Source, Spring Integration also provides a + MethodInvokingTarget adapter class. + MethodInvokingTarget target = new MethodInvokingTarget(); +target.setObject(new TargetObject()); +target.setMethodName("targetMethod"); +target.afterPropertiesSet(); +target.send(new StringMessage("test")); + Likewise, the corresponding XML configuration is very similar to that of + MethodInvokingSource. + ]]> + +
+
MessageChannel @@ -198,17 +240,17 @@ new GenericMessage<T>(T payload, MessageHeader headerToCopy) MessageBus - There is a rather obvious gap in what we have reviewed thus far. The - MessageChannel provides a receive() method that returns - a Message, and the MessageHandler provides a - handle() method that accepts a Message, but how do the - messages get passed from the channel to the handler? As mentioned earlier, the MessageBus - provides a runtime form of inversion of control, and so the short answer is: you don't need to worry about it. - Nevertheless since this is a reference guide, we will explore this in a bit of detail. + So far, you have seen that the MessageChannel provides a + receive() method that returns a Message, and the + MessageHandler provides a handle() method that accepts a + Message, but how do the messages get passed from the channel to the handler? + As mentioned earlier, the MessageBus provides a runtime form of inversion of control, and + one of the primary responsibilities that it assumes is connecting the channels to the handlers. It also connects + Sources and Targets to channels, and it manages the scheduling of pollers and dispatchers. The MessageBus is an example of a mediator. It performs a number of roles - mostly - by delegating to other strategies. One of its fundamental responsibilities is to manage registration of the + by delegating to other strategies. One of its main responsibilities is to manage registration of the MessageChannels and MessageHandlers. It provides the following methods: public void registerChannel(String name, MessageChannel channel) @@ -394,24 +436,26 @@ public void registerHandler(String name, MessageHandler handler,
MessageEndpoint - When MessageHandlers are registered with the MessageBus, - the bus assigns the handler to a dispatcher based on the provided schedule as described above. Internally, the - bus is creating and registering an instance that implements the MessageEndpoint - interface. This is where other handler metadata enters the picture (e.g. the concurrency settings). Basically, - you can consider the endpoint to be a composite handler built from a simple implementation of the - MessageHandler along with its metadata. In fact, the - MessageEndpoint does extend the MessageHandler - interface. - public interface MessageEndpoint extends MessageHandler { - String getName(); - Subscription getSubscription(); - ConcurrencyPolicy getConcurrencyPolicy(); -} + As described in , there are three implementations of the + MessageEndpoint interface: SourceEndpoint, + TargetEndpoint, and HandlerEndpoint. These endpoints provide the + metadata necessary for the MessageBus to manage Sources, + Targets, and MessageHandlers respectively. - When using the API, it's simpler to register handlers with metadata and leave the message endpoint as an internal - responsibility of the bus. However, it is possible to create endpoints directly. Spring Integration provides a - single implementation: DefaultMessageEndpoint. + For a SourceEndpoint, the MessageBus schedules a task for + polling the Source based on the provided schedule. + + + When a Target or MessageHandler is registered with + the MessageBus, the bus assigns it to a dispatcher that polls a + MessageChannel based on the provided schedule. Targets and handlers may also + provide concurrency settings in which case a thread pool will be created for asynchronous processing of messages. + + + Rather than programming to the API directly, it is simpler and more common to register sources, targets, and + handlers with either XML or annotation-based metadata. Then, the message endpoint is an internal responsibility + of the bus. The configuration options are discussed in detail in .
diff --git a/spring-integration-reference/src/overview.xml b/spring-integration-reference/src/overview.xml index 8e9bee4923..266e2346ee 100644 --- a/spring-integration-reference/src/overview.xml +++ b/spring-integration-reference/src/overview.xml @@ -100,31 +100,144 @@ framework while handling that object. It consists of a payload and header and has a unique identifier. The payload can be of any type and the header holds commonly required information such as timestamp, expiration, and return address. Developers can also store any arbitrary key-value properties or attributes in the header. + + + + + + +
+
+ Message Source + + Since a Spring Integration Message is a generic wrapper for any Object, there is no limit to the number of + potential sources for such messages. In fact, a Source implementation can act as an adapter that converts + Objects from any other system into Spring Integration Messages. + + + + + + To facilitate the conversion of Objects to Messages, Spring Integration also defines a strategy interface + for creating Messages called MessageCreator. While it is relatively easy to + implement Source directly, an adapter is also available for invoking arbitrary methods on plain Objects. Also, + several Source implementations are already available within the Spring Integration Adapters module. For a + detailed discussion of the various adapters, see . + +
+
+ Message Target + + Just as a Source enables Message reception, a Target handles the responsibility of sending Messages. As with + a Source, a Target can act as an adapter that converts Messages into the Objects expected by some other system. + + + + + + Spring Integration provides a strategy interface for mapping Messages to Objects called + MessaegMapper. The Target interface may be implemented directly, but an adapter + is also available for invoking arbitrary methods on plain Objects (delegating to the Message-mapping strategy + in the process). As with Sources, several Target implementations are already available within the Spring + Integration Adapters module as discussed in . + +
+
+ Message Handler + + As described above, the Source and Target components support conversion between Objects and Messages so that + application code and/or external systems can be connected to a Spring Integration application rather easily. + However, both Source and Target are unidirectional while the application code or external system to be invoked + may provide a return value. The Message Handler interface supports these request-reply scenarios. + + + + + + As with the Source and Target, Spring Integration also provides an adapter that itself implements the Message + Handler interface while supporting the invocation of arbitrary methods on plain Objects. The adapter relies + upon the message-creating and message-mapping strategies to handle the bidirectional Object/Message conversion. + For more information about the Message Handler, see .
Message Channel A Message Channel represents the "pipe" of a pipes-and-filters architecture. Producers send Messages to - a MessageChannel, and consumers receive Messages from a MessageChannel. The send and receive methods both come - in two forms: one that blocks indefinitely and one that accepts a timeout (for an immediate return, specify a - timeout value of 0). There are two main types of channels: Point-to-Point channels where - typically a single consumer will receive the Message and Publish-Subscribe channels where - all subscribers should receive the Message. + a channel, and consumers receive Messages from a channel. By providing both send and receive operations, a + Message Channel basically combines the roles of Source and Target. + + + + + + Spring Integration provides a number of different channel implementations: QueueChannel, PriorityChannel, + RendezvousChannel, DirectChannel, and ThreadLocalChannel. These are described in detail in + .
Message Endpoint - A Message Endpoint represents the "filter" of a pipes-and-filters architecture. The endpoint's primary role is - to connect application code to the messaging framework and to do so in a non-invasive manner. In other words, - the application code should have no awareness of the messaging framework. This is similar to the role of a - Controller in the MVC paradigm. Just as a Controller handles HTTP requests, the endpoint handles Messages. Just - as Controllers are mapped to URL patterns, endpoints are mapped to Message Channels. The goal is the same in - both cases: isolate application code from the infrastructure. In Spring Integration, the Message Endpoint - "hosts" and delegates to a MessageHandler strategy interface as described in - . + Thus far, the component diagrams show Consumers, Producers, and Requesters invoking the Source, Target, and + Message Handlers respectively. However, one of the primary goals of Spring Integration is to simplify the + development of enterprise integration solutions through inversion of control. This means + that you should not have to implement such Producers, Consumers, and Requesters directly. Instead, you should + be able to focus on your domain logic with an implementation based on plain Objects. Then, by providing + declarative configuration, you can "connect" your application code to the messaging infrastructure provided by + Spring Integration. The components responsible for these connections are Message Endpoints. + + A Message Endpoint represents the "filter" of a pipes-and-filters architecture. As mentioned above, the + endpoint's primary role is to connect application code to the messaging framework and to do so in a + non-invasive manner. In other words, the application code should have no awareness of the Message objects or + the Message Channels. This is similar to the role of a Controller in the MVC paradigm. Just as a Controller + handles HTTP requests, the Message Endpoint handles Messages. Just as Controllers are mapped to URL patterns, + Message Endpoints are mapped to Message Channels. The goal is the same in both cases: isolate application code + from the infrastructure. Spring Integration provides three types of endpoints - one for each of the component + types described above: Source Endpoint, Target Endpoint, and Handler Endpoint. + +
+ Source Endpoint + + A Source Endpoint connects any Source implementation to a Message Channel. The invocation of the Source's + receive operation is controlled by scheduling information provided within the Source Endpoint's + configuration. Any time the receive operation returns a non-null Message, it is sent to the channel. + + + + + + +
+
+ Target Endpoint + + A Target Endpoint connects a Message Channel to any Target implementation. The invocation of the Message + Channel's receive operation is controlled by scheduling information provided within the Target Endpoint's + configuration. Any time a non-null Message is received from the channel, it is sent to the Target. + + + + + + +
+
+ Handler Endpoint + + Since Message Handler's are capable of returning reply Messages, the Handler Endpoint has some additional + responsibilities. The general behavior is the same as the Target Endpoint, but the Handler Endpoint must + make a distinction between "input-channel" and "output-channel". Whenever the Message Handler does return + a reply Message, that Message is sent to the output channel. If no output channel has been configured, then + the reply will be sent to the channel specified as the Message header's "return address" if available. + + + + + + +
Message Router @@ -133,18 +246,11 @@ receiving a Message and then deciding what channel or channels should receive the Message next. Typically the decision is based upon the Message's content and/or metadata. A Message Router is often used as a dynamic alternative to configuring the input and output channels for an endpoint. - -
-
- Channel Adapter - - A Channel Adapter is used to connect components to a Message Channel when those components are not themselves - Message Endpoints. These adapters provide a mechanism for connecting to external systems, such as JMS queues - or a File system. Channel Adapters may be configured for input and/or output. An input (source) adapter will - receive (or poll for) data, convert that data to a Message, and then send that Message to its Message Channel. - An output (target) adapter is simply another type of MessageHandler, but when it - receives a Message, it will convert it to the target's expected type and then "send" it (publish to a JMS - queue, write to a File, etc.). + + + + +
diff --git a/spring-integration-reference/src/spring-integration-reference.xml b/spring-integration-reference/src/spring-integration-reference.xml index 985f155426..2efe4a82c5 100644 --- a/spring-integration-reference/src/spring-integration-reference.xml +++ b/spring-integration-reference/src/spring-integration-reference.xml @@ -5,7 +5,7 @@ Spring Integration Reference Manual Spring Integration - 1.0.0.M3 (Milestone 3) + 1.0.0.M4 (Milestone 4) @@ -38,5 +38,6 @@ + \ No newline at end of file