From b4828d4b08a269844be116590cf8671d3223c4e2 Mon Sep 17 00:00:00 2001 From: Mark Fisher Date: Thu, 17 Jan 2008 04:44:27 +0000 Subject: [PATCH] Added to the reference documentation --- .../reference/src/core-api.xml | 267 ++++++++++++++++++ .../reference/src/overview.xml | 123 +++++++- .../src/spring-integration-reference.xml | 4 +- 3 files changed, 390 insertions(+), 4 deletions(-) create mode 100644 spring-integration-reference/reference/src/core-api.xml diff --git a/spring-integration-reference/reference/src/core-api.xml b/spring-integration-reference/reference/src/core-api.xml new file mode 100644 index 0000000000..a1c29d3374 --- /dev/null +++ b/spring-integration-reference/reference/src/core-api.xml @@ -0,0 +1,267 @@ + + + Spring Integration Core API + +
+ Message + + The Spring Integration Message is a generic container for data. Any object can + be provided as the payload, and each Message also includes a header containing + user-extensible properties as key-value pairs. Here is the definition of the + Message interface: + public interface Message<T> { + Object getId(); + MessageHeader getHeader(); + T getPayload(); +} + And the header provides the following properties: + + Properties of the MessageHeader + + + + + Property Name + Property Type + + + + + timestamp + java.util.Date + + + expiration + java.util.Date + + + correlationId + java.lang.Object + + + replyChannelName + java.lang.String + + + sequenceNumber + int + + + sequenceSize + int + + + properties + java.util.Properties + + + attributes + Map<String,Object> + + + +
+ + + The base implementation of the Message interface is + GenericMessage<T>, and it provides two constructors: + new GenericMessage<T>(Object id, T payload); +new GenericMessage<T>(T payload); + When no id is provided, a random unique id will be generated. There are also two convenient subclasses available + currently: StringMessage and ErrorMessage. The latter accepts any + Throwable object as its payload. + + + The Message is obviously a very important part of the API. By encapsulating the + data in a generic wrapper, the messaging system can pass it around without any knowledge of the data's type. As + the system evolves to support new types, or when the types themselves are modified and/or extended, the messaging + system will not be affected by such changes. On the other hand, when some component in the messaging system + does require access to information about the Message, such + metadata can typically be stored to and retrieved from the metadata in the header (the 'properties' and + 'attributes'). + +
+ +
+ MessageChannel + + While the Message plays the crucial role of encapsulating data, it is the + MessageChannel that decouples message producers from message consumers. + Spring Integration's MessageChannel interface is defined as follows. + public interface MessageChannel { + String getName(); + boolean isPublishSubscribe(); + boolean send(Message message); + boolean send(Message message, long timeout); + Message receive(); + Message receive(long timeout); +} + The SimpleChannel implementation wraps a queue. It provides a no-argument constructor as + well as a constructor that accepts the queue capacity: + public SimpleChannel(int capacity) + When sending a message, the return value will be true if the message is sent successfully. + If the send call times out or is interrupted, then it will return false. Likewise when + receiving a message, the return value will be null in the case of a timeout or interrupt. + +
+ +
+ MessageHandler + + So far we have seen that generic message objects are sent-to and received-from simple channel objects. Here is + Spring Integration's callback interface for handling the Messages: + public interface MessageHandler { + Message<?> handle(Message<?> message); +} + The handler plays an important role, since it is typically responsible for translating between the generic + Message objects and the business components that consume the message payload. + That said, developers will rarely need to implement this callback directly. While that option will always be + available, we will soon discuss the higher-level configuration options including both annotation-driven + techniques and XML-based configuration with convenient namespace support. + +
+ +
+ 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. + + + 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 + MessageChannels and MessageHandlers. It provides + the following methods: + public void registerChannel(String name, MessageChannel channel) +public void registerChannel(String name, MessageChannel channel, DispatcherPolicy dispatcherPolicy) +public void registerHandler(String name, MessageHandler handler, Subscription subscription) +public void registerHandler(String name, MessageHandler handler, Subscription subscription, ConcurrencyPolicy concurrencyPolicy) + As those method signatures reveal, the message bus is handling several of the concerns here so that the channel + and handler objects can be as simple as possible. These responsibilities include the creation and lifecycle + management of message dispatchers, the activation of handler subscriptions, and the configuration of thread + pools. The bus coordinates all of that behavior based upon the metadata provided via these registration methods. + We will briefly take a look at each of those metadata objects. + + + The bus creates and manages dispatchers that pull messages from a channel in order to push those messages to + handlers registered on that channel. The DispatcherPolicy contains metadata for + configuring those dispatchers: + + Properties of the DispatcherPolicy + + + + + Property Name + Default Value + Description + + + + + maxMessagesPerTask + 1 + maximum number of messages to retrieve per poll + + + receiveTimeout + 1000 (milliseconds) + how long to block on the receive call (0 for no blocking, -1 for indefinite block) + + + rejectionLimit + 5 + maximum number of attempts to invoke handlers (e.g. no threads available) + + + retryInterval + 1000 (milliseconds) + amount of time to wait between successive attempts to invoke handlers + + + +
+ + + The bus registers handlers with a channel's dispatcher based upon the Subscription + metadata provided to the registerHandler() method. + + Properties of the Subscription + + + + + Property Name + Description + + + + + channel + the channel instance to subscribe to (an object reference) + + + channelName + the name of the channel to subscribe to - only used as a fallback if 'channel' is null + + + schedule + the scheduling metadata (see below) + + + +
+ The scheduling metadata is provided with an instance of the Schedule interface. + This is an abstraction designed to allow extensibility of schedulers for messaging tasks. Currently, there is + a single implementation called PollingSchedule that provides the following properties: + + Properties of the PollingSchedule + + + + + Property Name + Default Value + Description + + + + + period + N/A + the delay interval between each poll + + + initialDelay + 0 + the delay prior to the first poll + + + timeUnit + TimeUnit.MILLISECONDS + time unit for 'period' and 'initialDelay' + + + fixedRate + false + 'false' indicates fixed-delay (no backlog) + + + +
+ The PollingSchedule constructor requires the 'period' value. + + + The ConcurrencyPolicy is an optional parameter to provide when registering a handler. + It encapsulates two properties: 'coreSize' and 'maxSize'. When the MessageBus + registers a handler, it will use these properties to configure that handler's thread pool. These pool size + parameters are configurable on a per-handler basis since handlers may have differences in performance and + may have different expectations with regard to the volume of throughput. + +
+ \ No newline at end of file diff --git a/spring-integration-reference/reference/src/overview.xml b/spring-integration-reference/reference/src/overview.xml index bc949ce403..e62530fa91 100644 --- a/spring-integration-reference/reference/src/overview.xml +++ b/spring-integration-reference/reference/src/overview.xml @@ -1,3 +1,120 @@ - -TODO - \ No newline at end of file + + + Spring Integration Overview + +
+ Background + + One of the key themes of the Spring Framework is inversion of control. In its broadest + sense, this means that the framework handles responsibilities on behalf of the components that are managed within + its context. The components themselves are simplified since they are relieved of those responsibilities. For + example, dependency injection relieves the components of the responsibility of locating or + creating their dependencies. Likewise, aspect-oriented programming relieves business + components of generic cross-cutting concerns by modularizing them into reusable aspects. In each case, the end + result is a system that is easier to test, understand, maintain, and extend. + + + Furthermore, the Spring framework and portfolio provide a comprehensive programming model for building + enterprise applications. Developers benefit from the consistency of this model and especially the fact that it is + based upon well-established best practices such as programming to interfaces and favoring composition over + inheritance. Spring's simplified abstractions and powerful support libraries boost developer productivity while + simultaneously increasing the level of testability and portability. + + + Spring Integration is a new member of the Spring portfolio motivated by these same goals and principles. It + extends the Spring programming model into the messaging domain and builds upon the core enterprise integration + support to provide an even higher level of abstraction. It supports message-driven architectures where inversion + of control applies to runtime concerns, such as when certain business logic should execute + and where the response should be sent. It supports routing and transformation of messages so + that different transports and different data formats can be integrated without impacting testability. In other + words, the messaging and integration concerns are handled by the framework, so business components are further + isolated from the infrastructure and developers are relieved of complex integration responsibilities. + + + As an extension of the Spring programming model, Spring Integration provides a wide variety of configuration + options including annotations, XML with namespace support, XML with generic "bean" elements, and of course direct + usage of the underlying API. That API is based upon well-defined strategy interfaces and non-invasive, delegating + adapters. Spring Integration's design is inspired by the recognition of a strong affinity between common patterns + within Spring and the well-known Enterprise Integration Patterns + as described in the book of the same name by Gregor Hohpe and Bobby Woolf (Addison Wesley, 2003). Developers who + have read that book should be immediately comfortable with the Spring Integration concepts and terminology. + +
+ +
+ Goals and Principles + Spring Integration is motivated by the following goals: + + + Provide a simple model for implementing complex enterprise integration solutions. + + + Facilitate asynchronous, message-driven behavior within a Spring-based application. + + + Promote intuitive, incremental adoption for existing Spring users. + + + + Spring Integration is guided by the following principles: + + + Components should be loosely coupled for modularity and testability. + + + The framework should enforce separation of concerns between business logic and + integration logic. + + + Extension points should be abstract in nature but within well-defined boundaries to promote + reuse and portability. + + + +
+ +
+ Main Components +
+ Message + + In Spring Integration, a Message is a generic wrapper for any Java object combined with metadata used by the + 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 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. + +
+
+ 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 HttpRequests, the endpoint handles Messages. Just + as Controllers are mapped to URL patterns, endpoints are mapped to MessageChannels. The goal is the same in both + cases: isolate application code from the infrastructure. + +
+
+ Message Bus + + The Message Bus acts as a registry for Message Channels and Message Endpoints. It also encapsulates the + complexity of message retrieval and dispatching. Essentially, the Message Bus forms a logical extension of the + Spring application context into the messaging domain. For example, it will automatically detect Message Channel + and Message Endpoint components from within the application context. It handles the scheduling of pollers, the + creation of thread pools, and the lifecycle management of all messaging components that can be initialized, + started, and stopped. The Message Bus is the primary example of inversion of control within Spring Integration. + +
+
+ + \ No newline at end of file diff --git a/spring-integration-reference/reference/src/spring-integration-reference.xml b/spring-integration-reference/reference/src/spring-integration-reference.xml index 1e79b012d0..4de4fe7a29 100644 --- a/spring-integration-reference/reference/src/spring-integration-reference.xml +++ b/spring-integration-reference/reference/src/spring-integration-reference.xml @@ -2,10 +2,11 @@ + ]> - Reference Manual + Spring Integration Reference Manual Spring Integration 1.0 Milestone 1 @@ -32,5 +33,6 @@ &overview; + &core-api; \ No newline at end of file