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 motivated by these same goals and principles. It extends the Spring programming model into the messaging domain and builds upon Spring’s existing 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, 2004). Developers who have read that book should be immediately comfortable with the Spring Integration concepts and terminology.

Spring Integration is motivated by the following goals:

Spring Integration is guided by the following principles:

From the vertical perspective, a layered architecture facilitates separation of concerns, and interface-based contracts between layers promote loose coupling. Spring-based applications are typically designed this way, and the Spring framework and portfolio provide a strong foundation for following this best practice for the full-stack of an enterprise application. Message-driven architectures add a horizontal perspective, yet these same goals are still relevant. Just as "layered architecture" is an extremely generic and abstract paradigm, messaging systems typically follow the similarly abstract "pipes-and-filters" model. The "filters" represent any component that is capable of producing and/or consuming messages, and the "pipes" transport the messages between filters so that the components themselves remain loosely-coupled. It is important to note that these two high-level paradigms are not mutually exclusive. The underlying messaging infrastructure that supports the "pipes" should still be encapsulated in a layer whose contracts are defined as interfaces. Likewise, the "filters" themselves would typically be managed within a layer that is logically above the application’s service layer, interacting with those services through interfaces much in the same way that a web-tier would.

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 ideally 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. These concepts are discussed at length along with all of the patterns that follow in the Enterprise Integration Patterns book. Here, we provide only a high-level description of the main endpoint types supported by Spring Integration and their roles. The chapters that follow will elaborate and provide sample code as well as configuration examples.

Throughout this document you will see references to XML namespace support for declaring elements in a Spring Integration flow. This support is provided by a series of namespace parsers that generate appropriate bean definitions to implement a particular component. For example, many endpoints consist of a MessageHandler bean and a ConsumerEndpointFactoryBean into which the handler and an input channel name are injected.

The first time a Spring Integration namespace element is encountered, the framework automatically declares a number of beans that are used to support the runtime environment (task scheduler, implicit channel creator, etc).

The @EnableIntegration annotation is also useful when you have a parent context with no Spring Integration components and 2 or more child contexts that use Spring Integration. It enables these common components to be declared once only, in the parent context.

The @EnableIntegration annotation registers many infrastructure components with the application context:

The @IntegrationComponentScan annotation has also been introduced to permit classpath scanning. This annotation plays a similar role as the standard Spring Framework @ComponentScan annotation, but it is restricted just to Spring Integration specific components and annotations, which aren’t reachable by the standard Spring Framework component scan mechanism. For example Section 8.3.6, “@MessagingGateway Annotation”.

The @EnablePublisher annotation has been introduced to register a PublisherAnnotationBeanPostProcessor bean and configure the default-publisher-channel for those @Publisher annotations which are provided without a channel attribute. If more than one @EnablePublisher annotation is found, they must all have the same value for the default channel. See Section B.1.1, “Annotation-driven approach via @Publisher annotation” for more information.

The @GlobalChannelInterceptor annotation has been introduced to mark ChannelInterceptor beans for global channel interception. This annotation is an analogue of the <int:channel-interceptor> xml element (see the section called “Global Channel Interceptor Configuration”). @GlobalChannelInterceptor annotations can be placed at the class level (with a @Component stereotype annotation), or on @Bean methods within @Configuration classes. In either case, the bean must be a ChannelInterceptor.

The @IntegrationConverter annotation has been introduced to mark Converter, GenericConverter or ConverterFactory beans as candidate converters for integrationConversionService. This annotation is an analogue of the <int:converter> xml element (see Section 8.1.6, “Payload Type Conversion”). @IntegrationConverter annotations can be placed at the class level (with a @Component stereotype annotation), or on @Bean methods within @Configuration classes.

Also see Section F.6, “Annotation Support” for more information about Messaging Annotations.

It is generally recommended that you use plain old java objects (POJOs) whenever possible and only expose the framework in your code when absolutely necessary.

If you do expose the framework to your classes, there are some considerations that need to be taken into account, especially during application startup; some of these are listed here.

With XML configuration and Spring Integration Namespace support, the XML Parsers hide how target beans are built and wired together. For Java & Annotation Configuration, it is important to understand the Framework API for the target end-user applications.

The first class citizens for EIP implementation are Message, Channel and Endpoint (see Section 3.3, “Main Components” above). Their implementations (contracts) are:

The first two are simple enough to understand how to implement, configure and use, respectively; the last one deserves more review.

The AbstractEndpoint is widely used throughout the Framework for different component implementations; its main implementations are:

Using Messaging Annotations and/or Java DSL, you shouldn’t worry about these components, because the Framework produces them automatically via appropriate annotations and BeanPostProcessor s. When building components manually, the ConsumerEndpointFactoryBean should be used to help to determine the target AbstractEndpoint implementation based on the provided inputChannel property.

On the other hand, the ConsumerEndpointFactoryBean exhibits an another first class citizens in the Framework - org.springframework.messaging.MessageHandler. The goal of the implementation of this class is to handle the message consumed by the endpoint from the channel. All EIP components in Spring Integration are MessageHandler implementations, e.g. AggregatingMessageHandler, MessageTransformingHandler, AbstractMessageSplitter etc.; as well as the target protocol outbound adapters are implementations, too, e.g. FileWritingMessageHandler, HttpRequestExecutingMessageHandler, AbstractMqttMessageHandler etc. When you develop Spring Integration applications with Java & Annotation Configuration, you should take a look into the Spring Integration module to find an appropriate MessageHandler implementation to be used for the @ServiceActivator configuration. For example to send an XMPP message (see Chapter 36, XMPP Support) we should configure something like this:

@Bean
@ServiceActivator(inputChannel = "input")
public MessageHandler sendChatMessageHandler(XMPPConnection xmppConnection) {
    ChatMessageSendingMessageHandler handler = new ChatMessageSendingMessageHandler(xmppConnection);

    DefaultXmppHeaderMapper xmppHeaderMapper = new DefaultXmppHeaderMapper();
    xmppHeaderMapper.setRequestHeaderNames("*");
    handler.setHeaderMapper(xmppHeaderMapper);

    return handler;
}

The MessageHandler implementations represent the outbound and processing part of the message flow.

The inbound message flow side has its own components, which are divided to the polling and listening behavior. The listening components are pretty simple and typically requires only one target class implementation to be ready to produce messages. Listening components can be one-way MessageProducerSupport implementations, e.g. AbstractMqttMessageDrivenChannelAdapter and ImapIdleChannelAdapter; and request-reply - MessagingGatewaySupport implementations, e.g. AmqpInboundGateway and AbstractWebServiceInboundGateway.

Polling inbound endpoints are for those protocols which don’t provide a listener API or aren’t intended for such a behavior. For example any File based protocol, as an FTP, any data bases (RDBMS or NoSQL) etc.

These inbound endpoints consist with two components: the poller configuration, to initiate the polling task periodically, and message source class to read data from the target protocol and produce a message for the downstream integration flow. The first class, for poller configuration, is SourcePollingChannelAdapter. It is one more AbstractEndpoint implementation, but especially for the polling purpose for initiating an integration flow. Typically, with the Messaging Annotations or Java DSL, you shouldn’t worry about this class, the Framework produces a bean for it, based on the @InboundChannelAdapter configuration or Java DSL particular Builder.

The message source components are more important for the target application development and they all implement the MessageSource interface, e.g. MongoDbMessageSource and AbstractTwitterMessageSource. With that in mind, our config for reading data from an RDBMS table with JDBC may look like:

@Bean
@InboundChannelAdapter(value = "fooChannel", poller = @Poller(fixedDelay="5000"))
public MessageSource<?> storedProc(DataSource dataSource) {
    return new JdbcPollingChannelAdapter(dataSource, "SELECT * FROM foo where status = 0");
}

All the required inbound and outbound classes for the target protocols you can find in the particular Spring Integration module, in most cases in the respective package. For example spring-integration-websocket adapters are:

If you are familiar with Spring Integration XML configuration already, starting with version 4.3, we provide in the XSD elements definitions the description with the pointer which target classes are used to produce beans for the adapter or gateway, for example:

<xsd:element name="outbound-async-gateway">
    <xsd:annotation>
		<xsd:documentation>
Configures a Consumer Endpoint for the 'o.s.i.amqp.outbound.AsyncAmqpOutboundGateway'
that will publish an AMQP Message to the provided Exchange and expect a reply Message.
The sending thread returns immediately; the reply is sent asynchronously; uses 'AsyncRabbitTemplate.sendAndReceive()'.
       </xsd:documentation>
	</xsd:annotation>