7/31/22, 5:51 PM Integration

Integration

Version 5.3.22

Back to index

1. REST Endpoints
1.1.  RestTemplate
1.1.1. Initialization
URIs
Headers
1.1.2. Body
1.1.3. Message Conversion
1.1.4. Jackson JSON Views
Multipart
1.2. Using  AsyncRestTemplate  (Deprecated)
2. Remoting and Web Services
2.1. AMQP
2.2. Considerations when Choosing a Technology
2.3. Java Web Services
2.3.1. Exposing Servlet-based Web Services by Using JAX-WS
2.3.2. Exporting Standalone Web Services by Using JAX-WS
2.3.3. Exporting Web Services by Using JAX-WS RI’s Spring Support
2.3.4. Accessing Web Services by Using JAX-WS
2.4. RMI (Deprecated)
2.4.1. Exporting the Service by Using  RmiServiceExporter
2.4.2. Linking in the Service at the Client
2.5. Using Hessian to Remotely Call Services through HTTP (Deprecated)
2.5.1. Hessian
2.5.2. Exposing Your Beans by Using  HessianServiceExporter
2.5.3. Linking in the Service on the Client
2.5.4. Applying HTTP Basic Authentication to a Service Exposed through Hessian

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 1/15
7/31/22, 5:51 PM Integration

2.6. Spring HTTP Invoker (Deprecated)

2.6.1. Exposing the Service Object
2.6.2. Linking in the Service at the Client
2.7. JMS (Deprecated)
2.7.1. Server-side Configuration
2.7.2. Client-side Configuration
3. Enterprise JavaBeans (EJB) Integration
3.1. Accessing EJBs
3.1.1. Concepts
3.1.2. Accessing Local SLSBs
3.1.3. Accessing Remote SLSBs
3.1.4. Accessing EJB 2.x SLSBs Versus EJB 3 SLSBs
4. JMS (Java Message Service)
4.1. Using Spring JMS
4.1.1. Using  JmsTemplate
4.1.2. Connections
Caching Messaging Resources
Using  SingleConnectionFactory
Using  CachingConnectionFactory
4.1.3. Destination Management
4.1.4. Message Listener Containers
Using  SimpleMessageListenerContainer
Using  DefaultMessageListenerContainer
4.1.5. Transaction Management
4.2. Sending a Message
4.2.1. Using Message Converters
4.2.2. Using  SessionCallback  and  ProducerCallback
4.3. Receiving a Message
4.3.1. Synchronous Reception
4.3.2. Asynchronous reception: Message-Driven POJOs
4.3.3. Using the  SessionAwareMessageListener  Interface
4.3.4. Using  MessageListenerAdapter
4.3.5. Processing Messages Within Transactions
4.4. Support for JCA Message Endpoints

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 2/15
7/31/22, 5:51 PM Integration

4.5. Annotation-driven Listener Endpoints

4.5.1. Enable Listener Endpoint Annotations
4.5.2. Programmatic Endpoint Registration
4.5.3. Annotated Endpoint Method Signature
4.5.4. Response Management
4.6. JMS Namespace Support
5. JMX
5.1. Exporting Your Beans to JMX
5.1.1. Creating an MBeanServer
5.1.2. Reusing an Existing  MBeanServer
5.1.3. Lazily Initialized MBeans
5.1.4. Automatic Registration of MBeans
5.1.5. Controlling the Registration Behavior
5.2. Controlling the Management Interface of Your Beans
5.2.1. Using the  MBeanInfoAssembler  Interface
5.2.2. Using Source-level Metadata: Java Annotations
5.2.3. Source-level Metadata Types
5.2.4. Using the  AutodetectCapableMBeanInfoAssembler  Interface
5.2.5. Defining Management Interfaces by Using Java Interfaces
5.2.6. Using  MethodNameBasedMBeanInfoAssembler
5.3. Controlling  ObjectName  Instances for Your Beans
5.3.1. Reading  ObjectName  Instances from Properties
5.3.2. Using  MetadataNamingStrategy
5.3.3. Configuring Annotation-based MBean Export
5.4. Using JSR-160 Connectors
5.4.1. Server-side Connectors
5.4.2. Client-side Connectors
5.4.3. JMX over Hessian or SOAP
5.5. Accessing MBeans through Proxies
5.6. Notifications
5.6.1. Registering Listeners for Notifications
5.6.2. Publishing Notifications
5.7. Further Resources
6. Email

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 3/15
7/31/22, 5:51 PM Integration

6.1. Usage
6.1.1. Basic  MailSender  and  SimpleMailMessage  Usage
6.1.2. Using  JavaMailSender  and  MimeMessagePreparator
6.2. Using the JavaMail  MimeMessageHelper
6.2.1. Sending Attachments and Inline Resources
Attachments
Inline Resources
6.2.2. Creating Email Content by Using a Templating Library
7. Task Execution and Scheduling
7.1. The Spring  TaskExecutor  Abstraction
7.1.1.  TaskExecutor  Types
7.1.2. Using a  TaskExecutor
7.2. The Spring  TaskScheduler  Abstraction
7.2.1.  Trigger  Interface
7.2.2.  Trigger  Implementations
7.2.3.  TaskScheduler  implementations
7.3. Annotation Support for Scheduling and Asynchronous Execution
7.3.1. Enable Scheduling Annotations
7.3.2. The  @Scheduled  annotation
7.3.3. The  @Async  annotation
7.3.4. Executor Qualification with  @Async
7.3.5. Exception Management with  @Async
7.4. The  task  Namespace
7.4.1. The 'scheduler' Element
7.4.2. The  executor  Element
7.4.3. The 'scheduled-tasks' Element
7.5. Cron Expressions
7.5.1. Macros
7.6. Using the Quartz Scheduler
7.6.1. Using the  JobDetailFactoryBean
7.6.2. Using the  MethodInvokingJobDetailFactoryBean
7.6.3. Wiring up Jobs by Using Triggers and  SchedulerFactoryBean
8. Cache Abstraction
8.1. Understanding the Cache Abstraction

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 4/15
7/31/22, 5:51 PM Integration

8.2. Declarative Annotation-based Caching

8.2.1. The  @Cacheable  Annotation
Default Key Generation
Custom Key Generation Declaration
Default Cache Resolution
Custom Cache Resolution
Synchronized Caching
Conditional Caching
Available Caching SpEL Evaluation Context
8.2.2. The  @CachePut  Annotation
8.2.3. The  @CacheEvict  annotation
8.2.4. The  @Caching  Annotation
8.2.5. The  @CacheConfig  annotation
8.2.6. Enabling Caching Annotations
8.2.7. Using Custom Annotations
8.3. JCache (JSR-107) Annotations
8.3.1. Feature Summary
8.3.2. Enabling JSR-107 Support
8.4. Declarative XML-based Caching
8.5. Configuring the Cache Storage
8.5.1. JDK  ConcurrentMap -based Cache
8.5.2. Ehcache-based Cache
8.5.3. Caffeine Cache
8.5.4. GemFire-based Cache
8.5.5. JSR-107 Cache
8.5.6. Dealing with Caches without a Backing Store
8.6. Plugging-in Different Back-end Caches
8.7. How can I Set the TTL/TTI/Eviction policy/XXX feature?
9. Appendix
9.1. XML Schemas
9.1.1. The  jee  Schema
<jee:jndi-lookup/> (simple)
<jee:jndi-lookup/>  (with Single JNDI Environment Setting)

<jee:jndi-lookup/>  (with Multiple JNDI Environment Settings)

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 5/15
7/31/22, 5:51 PM Integration

<jee:jndi-lookup/>  (Complex)

<jee:local-slsb/>  (Simple)

<jee:local-slsb/>  (Complex)

<jee:remote-slsb/>
9.1.2. The  jms  Schema
9.1.3. Using  <context:mbean-export/>
9.1.4. The  cache  Schema

This part of the reference documentation covers Spring Framework’s integration with a number
of technologies.

1. REST Endpoints
The Spring Framework provides two choices for making calls to REST endpoints:

RestTemplate : The original Spring REST client with a synchronous, template method API.

WebClient: a non-blocking, reactive alternative that supports both synchronous and

asynchronous as well as streaming scenarios.

As of 5.0 the  RestTemplate  is in maintenance mode, with only minor requests for changes
and bugs to be accepted going forward. Please, consider using the WebClient which offers
a more modern API and supports sync, async, and streaming scenarios.

1.1.  RestTemplate
The  RestTemplate  provides a higher level API over HTTP client libraries. It makes it easy to
invoke REST endpoints in a single line. It exposes the following groups of overloaded methods:

Table 1. RestTemplate methods

Method Description
group

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 6/15
7/31/22, 5:51 PM Integration

Method Description
group

getFor Retrieves a representation via GET.

Object

getFor Retrieves a  ResponseEntity  (that is, status, headers, and body) by using GET.
Entity

headFo Retrieves all headers for a resource by using HEAD.

rHeade
rs

postFo Creates a new resource by using POST and returns the  Location  header from the
rLocat
response.
ion

postFo Creates a new resource by using POST and returns the representation from the
rObjec
response.
t

postFo Creates a new resource by using POST and returns the representation from the
rEntit
response.
y

put Creates or updates a resource by using PUT.

patchF Updates a resource by using PATCH and returns the representation from the
orObje
response. Note that the JDK  HttpURLConnection  does not support  PATCH , but
ct
Apache HttpComponents and others do.

delete Deletes the resources at the specified URI by using DELETE.

option Retrieves allowed HTTP methods for a resource by using ALLOW.

sForAl
low

exchan More generalized (and less opinionated) version of the preceding methods that
ge
provides extra flexibility when needed. It accepts a  RequestEntity  (including
HTTP method, URL, headers, and body as input) and returns a  ResponseEntity .

These methods allow the use of  ParameterizedTypeReference  instead of  Class  to
specify a response type with generics.

execut The most generalized way to perform a request, with full control over request
e
preparation and response extraction through callback interfaces.

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 7/15
7/31/22, 5:51 PM Integration

1.1.1. Initialization
The default constructor uses  java.net.HttpURLConnection  to perform requests. You can switch to
a different HTTP library with an implementation of  ClientHttpRequestFactory . There is built-in
support for the following:

Apache HttpComponents

Netty

OkHttp

For example, to switch to Apache HttpComponents, you can use the following:

RestTemplate template = new RestTemplate(new HttpComponentsClientHttpRequestFactory());

Each  ClientHttpRequestFactory  exposes configuration options specific to the underlying HTTP

client library — for example, for credentials, connection pooling, and other details.

Note that the  java.net  implementation for HTTP requests can raise an exception when
accessing the status of a response that represents an error (such as 401). If this is an
issue, switch to another HTTP client library.

URIs
Many of the  RestTemplate  methods accept a URI template and URI template variables, either as
a  String  variable argument, or as  Map<String,String> .

The following example uses a  String  variable argument:

String result = restTemplate.getForObject(

"https://example.com/hotels/{hotel}/bookings/{booking}", String.class, "42", "21");

The following example uses a  Map<String, String> :

Map<String, String> vars = Collections.singletonMap("hotel", "42");

String result = restTemplate.getForObject(

"https://example.com/hotels/{hotel}/rooms/{hotel}", String.class, vars);

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 8/15
7/31/22, 5:51 PM Integration

Keep in mind URI templates are automatically encoded, as the following example shows:

restTemplate.getForObject("https://example.com/hotel list", String.class);

// Results in request to "https://example.com/hotel%20list"

You can use the  uriTemplateHandler  property of  RestTemplate  to customize how URIs are
encoded. Alternatively, you can prepare a  java.net.URI  and pass it into one of
the  RestTemplate  methods that accepts a  URI .

For more details on working with and encoding URIs, see URI Links.

Headers
You can use the  exchange()  methods to specify request headers, as the following example
shows:

String uriTemplate = "https://example.com/hotels/{hotel}";

URI uri = UriComponentsBuilder.fromUriString(uriTemplate).build(42);

RequestEntity<Void> requestEntity = RequestEntity.get(uri)

.header("MyRequestHeader", "MyValue")

.build();

ResponseEntity<String> response = template.exchange(requestEntity, String.class);

String responseHeader = response.getHeaders().getFirst("MyResponseHeader");

String body = response.getBody();

You can obtain response headers through many  RestTemplate  method variants that
return  ResponseEntity .

1.1.2. Body
Objects passed into and returned from  RestTemplate  methods are converted to and from raw
content with the help of an  HttpMessageConverter .

On a POST, an input object is serialized to the request body, as the following example shows:

URI location = template.postForLocation("https://example.com/people", person);

You need not explicitly set the Content-Type header of the request. In most cases, you can find a
compatible message converter based on the source  Object  type, and the chosen message
converter sets the content type accordingly. If necessary, you can use the  exchange  methods to
https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 9/15
7/31/22, 5:51 PM Integration

explicitly provide the  Content-Type  request header, and that, in turn, influences what message
converter is selected.

On a GET, the body of the response is deserialized to an output  Object , as the following
example shows:

Person person = restTemplate.getForObject("https://example.com/people/{id}", Person.class, 42

The  Accept  header of the request does not need to be explicitly set. In most cases, a
compatible message converter can be found based on the expected response type, which then
helps to populate the  Accept  header. If necessary, you can use the  exchange  methods to
provide the  Accept  header explicitly.

By default,  RestTemplate  registers all built-in message converters, depending on classpath

checks that help to determine what optional conversion libraries are present. You can also set the
message converters to use explicitly.

1.1.3. Message Conversion

WebFlux

The  spring-web  module contains the  HttpMessageConverter  contract for reading and writing the
body of HTTP requests and responses
through  InputStream  and  OutputStream .  HttpMessageConverter  instances are used on the client
side (for example, in the  RestTemplate ) and on the server side (for example, in Spring MVC
REST controllers).

Concrete implementations for the main media (MIME) types are provided in the framework and
are, by default, registered with the  RestTemplate  on the client side and
with  RequestMappingHandlerAdapter  on the server side (see Configuring Message Converters).

The implementations of  HttpMessageConverter  are described in the following sections. For all
converters, a default media type is used, but you can override it by setting
the  supportedMediaTypes  bean property. The following table describes each implementation:

Table 2. HttpMessageConverter Implementations

MessageConverter Description

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 10/15
7/31/22, 5:51 PM Integration

MessageConverter Description

StringHttpMessageC An  HttpMessageConverter  implementation that can read and

onverter
write  String  instances from the HTTP request and response. By
default, this converter supports all text media types ( text/* ) and
writes with a  Content-Type  of  text/plain .

FormHttpMessageCon An  HttpMessageConverter  implementation that can read and write

verter
form data from the HTTP request and response. By default, this
converter reads and writes the  application/x-www-form-
urlencoded  media type. Form data is read from and written into
a  MultiValueMap<String, String> . The converter can also write (but
not read) multipart data read from a  MultiValueMap<String, Object> .
By default,  multipart/form-data  is supported. As of Spring
Framework 5.2, additional multipart subtypes can be supported for
writing form data. Consult the javadoc
for  FormHttpMessageConverter  for further details.

ByteArrayHttpMessa An  HttpMessageConverter  implementation that can read and write byte
geConverter
arrays from the HTTP request and response. By default, this converter
supports all media types ( */* ) and writes with a  Content-
Type  of  application/octet-stream . You can override this by setting
the  supportedMediaTypes  property and
overriding  getContentType(byte[]) .

MarshallingHttpMes An  HttpMessageConverter  implementation that can read and write

sageConverter
XML by using Spring’s  Marshaller  and  Unmarshaller  abstractions
from the  org.springframework.oxm  package. This converter requires
a  Marshaller  and  Unmarshaller  before it can be used. You can inject
these through constructor or bean properties. By default, this converter
supports  text/xml  and  application/xml .

MappingJackson2Htt An  HttpMessageConverter  implementation that can read and write

pMessageConverter
JSON by using Jackson’s  ObjectMapper . You can customize JSON
mapping as needed through the use of Jackson’s provided
annotations. When you need further control (for cases where custom
JSON serializers/deserializers need to be provided for specific types),
you can inject a custom  ObjectMapper  through
the  ObjectMapper  property. By default, this converter
supports  application/json .

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 11/15
7/31/22, 5:51 PM Integration

MessageConverter Description

MappingJackson2Xml An  HttpMessageConverter  implementation that can read and write

HttpMessageConvert
XML by using Jackson XML extension’s  XmlMapper . You can
er
customize XML mapping as needed through the use of JAXB or
Jackson’s provided annotations. When you need further control (for
cases where custom XML serializers/deserializers need to be provided
for specific types), you can inject a custom  XmlMapper  through
the  ObjectMapper  property. By default, this converter
supports  application/xml .

SourceHttpMessageC An  HttpMessageConverter  implementation that can read and

onverter
write  javax.xml.transform.Source  from the HTTP request and
response. Only  DOMSource ,  SAXSource , and  StreamSource  are
supported. By default, this converter
supports  text/xml  and  application/xml .

BufferedImageHttpM An  HttpMessageConverter  implementation that can read and

essageConverter
write  java.awt.image.BufferedImage  from the HTTP request and
response. This converter reads and writes the media type supported
by the Java I/O API.

1.1.4. Jackson JSON Views

You can specify a Jackson JSON View to serialize only a subset of the object properties, as the
following example shows:

MappingJacksonValue value = new MappingJacksonValue(new User("eric", "7!jd#h23"));

value.setSerializationView(User.WithoutPasswordView.class);

RequestEntity<MappingJacksonValue> requestEntity =

RequestEntity.post(new URI("https://example.com/user")).body(value);

ResponseEntity<String> response = template.exchange(requestEntity, String.class);

Multipart
To send multipart data, you need to provide a  MultiValueMap<String, Object>  whose values
may be an  Object  for part content, a  Resource  for a file part, or an  HttpEntity  for part content
with headers. For example:

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 12/15
7/31/22, 5:51 PM Integration

MultiValueMap<String, Object> parts = new LinkedMultiValueMap<>();

parts.add("fieldPart", "fieldValue");

parts.add("filePart", new FileSystemResource("...logo.png"));

parts.add("jsonPart", new Person("Jason"));

HttpHeaders headers = new HttpHeaders();

headers.setContentType(MediaType.APPLICATION_XML);

parts.add("xmlPart", new HttpEntity<>(myBean, headers));

In most cases, you do not have to specify the  Content-Type  for each part. The content type is
determined automatically based on the  HttpMessageConverter  chosen to serialize it or, in the
case of a  Resource  based on the file extension. If necessary, you can explicitly provide
the  MediaType  with an  HttpEntity  wrapper.

Once the  MultiValueMap  is ready, you can pass it to the  RestTemplate , as show below:

MultiValueMap<String, Object> parts = ...;

template.postForObject("https://example.com/upload", parts, Void.class);

If the  MultiValueMap  contains at least one non- String  value, the  Content-Type  is set
to  multipart/form-data  by the  FormHttpMessageConverter . If
the  MultiValueMap  has  String  values the  Content-Type  is defaulted to  application/x-www-
form-urlencoded . If necessary the  Content-Type  may also be set explicitly.

1.2. Using  AsyncRestTemplate  (Deprecated)

The  AsyncRestTemplate  is deprecated. For all use cases where you might consider
using  AsyncRestTemplate , use the WebClient instead.

2. Remoting and Web Services

Spring provides support for remoting with various technologies. The remoting support eases the
development of remote-enabled services, implemented via Java interfaces and objects as input
and output. Currently, Spring supports the following remoting technologies:

Java Web Services: Spring provides remoting support for web services through JAX-WS.

AMQP: Remoting via AMQP as the underlying protocol is supported by the separate Spring
AMQP project.

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 13/15
7/31/22, 5:51 PM Integration

As of Spring Framework 5.3, support for several remoting technologies is now deprecated
for security reasons and broader industry support. Supporting infrastructure will be
removed from Spring Framework for its next major release.

The following remoting technologies are now deprecated and will not be replaced:

Remote Method Invocation (RMI): Through the use

of  RmiProxyFactoryBean  and  RmiServiceExporter , Spring supports both traditional RMI
(with  java.rmi.Remote  interfaces and  java.rmi.RemoteException ) and transparent remoting
through RMI invokers (with any Java interface).

Spring HTTP Invoker (Deprecated): Spring provides a special remoting strategy that allows
for Java serialization though HTTP, supporting any Java interface (as the RMI invoker does).
The corresponding support classes
are  HttpInvokerProxyFactoryBean  and  HttpInvokerServiceExporter .

Hessian: By using Spring’s  HessianProxyFactoryBean  and the  HessianServiceExporter , you

can transparently expose your services through the lightweight binary HTTP-based protocol
provided by Caucho.

JMS (Deprecated): Remoting via JMS as the underlying protocol is supported through
the  JmsInvokerServiceExporter  and  JmsInvokerProxyFactoryBean  classes in the  spring-
jms  module.

While discussing the remoting capabilities of Spring, we use the following domain model and
corresponding services:

public class Account implements Serializable {

private String name;

public String getName(){

return name;

public void setName(String name) {

this.name = name;

public interface AccountService {

public void insertAccount(Account account);

public List<Account> getAccounts(String name);

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 14/15
7/31/22, 5:51 PM Integration

// the implementation doing nothing at the moment

public class AccountServiceImpl implements AccountService {

public void insertAccount(Account acc) {

// do something...

public List<Account> getAccounts(String name) {

// do something...

This section starts by exposing the service to a remote client by using RMI and talk a bit about
the drawbacks of using RMI. It then continues with an example that uses Hessian as the
protocol.

2.1. AMQP
Remoting via AMQP as the underlying protocol is supported in the Spring AMQP project. For
further details please visit the Spring Remoting section of the Spring AMQP reference.

Auto-detection is not implemented for remote interfaces.

The main reason why auto-detection of implemented interfaces does not occur for remote
interfaces is to avoid opening too many doors to remote callers. The target object might
implement internal callback interfaces, such
as  InitializingBean  or  DisposableBean  which one would not want to expose to callers.

Offering a proxy with all interfaces implemented by the target usually does not matter in the
local case. However, when you export a remote service, you should expose a specific
service interface, with specific operations intended for remote usage. Besides internal
callback interfaces, the target might implement multiple business interfaces, with only one
of them intended for remote exposure. For these reasons, we require such a service
interface to be specified.

This is a trade-off between configuration convenience and the risk of accidental exposure
of internal methods. Always specifying a service interface is not too much effort and puts
you on the safe side regarding cont

https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#spring-integration 15/15