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:
+
+
+
+ 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