Getting Started with Spring JMS – Spring JMS的入门

最后修改: 2016年 10月 17日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

Spring provides a JMS Integration framework that simplifies the use of the JMS API. This article introduces the basic concepts of such integration.

Spring提供了一个JMS集成框架，简化了JMS API的使用。这篇文章介绍了这种集成的基本概念。

2. Maven Dependency

2.Maven的依赖性

In order to use Spring JMS in our application, we need to add necessary artifacts in the pom.xml:

为了在我们的应用程序中使用Spring JMS，我们需要在pom.xml中添加必要的构件。

<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jms</artifactId>
    <version>4.3.3.RELEASE</version>
</dependency>

The newest version of the artifact can be found here.

神器的最新版本可以在这里找到。

3. The JmsTemplate

3. JmsTemplate

JmsTemplate class handles the creation and releasing of resources when sending or synchronously receiving messages.

JmsTemplate类在发送或同步接收消息时处理资源的创建和释放。

Hence the class that uses this JmsTemplate only needs to implement callback interfaces as specified in the method definition.

因此，使用这个JmsTemplate的类只需要实现方法定义中指定的回调接口。

Starting with Spring 4.1, the JmsMessagingTemplate is built on top of JmsTemplate which provides an integration with the messaging abstraction, i.e., org.springframework.messaging.Message. This, in turn, allows us to create a message to send in a generic manner.

从Spring 4.1开始，JmsMessagingTemplate建立在JmsTemplate之上，它提供了与消息传递抽象的集成，即org.springframework.messaging.Message。这反过来又允许我们创建一个消息，以通用方式发送。

4. Connection Management

4.连接管理

In order to connect and be able to send/receive messages, we need to configure a ConnectionFactory.

为了连接并能够发送/接收消息，我们需要配置一个ConnectionFactory。

A ConnectionFactory is one of the JMS administered objects which are preconfigured by an administrator. A client with the help of the configuration will make the connection with a JMS provider.

ConnectionFactory是JMS管理的对象之一，它是由管理员预先配置的。在配置的帮助下，客户端将与JMS提供者建立连接。

Spring provides 2 types of ConnectionFactory:

Spring提供了2种类型的ConnectionFactory。

  • SingleConnectionFactory – is an implementation of ConnectionFactory interface, that will return the same connection on all createConnection() calls and ignore calls to close()
  • CachingConnectionFactory – extends the functionality of the SingleConnectionFactory and adds enhances it with a caching of Sessions, MessageProducers, and MessageConsumers

5. Destination Management

5.目的地管理

As discussed above, along with the ConnectionFactory, destinations are also JMS administered objects and can be stored and retrieved from a JNDI.

如上所述，与ConnectionFactory一起，目的地也是JMS管理的对象，可以从JNDI中存储和检索。

Spring provides generic resolvers like DynamicDestinationResolver and specific resolvers such as JndiDestinationResolver.

Spring提供了像DynamicDestinationResolver这样的通用解析器和像JndiDestinationResolver这样的特殊解析器。

The JmsTemplate will delegate the resolution of the destination name to one of the implementations basing on our selection.

JmsTemplate将根据我们的选择，把目标名称的解析委托给其中一个实现。

It will also provide a property called defaultDestination – which will be used with send and receive operations that do not refer to a specific destination.

它还将提供一个名为defaultDestination的属性–它将被用于send和receive操作，这些操作并不指向一个特定的目的地。

6. Message Conversion

6.信息转换

Spring JMS would be incomplete without the support of Message Converters.

如果没有消息转换器的支持，Spring JMS是不完整的。

The default conversion strategy used by JmsTemplate for both ConvertAndSend() and ReceiveAndConvert() operations is the SimpleMessageConverter class.

JmsTemplate为ConvertAndSend()和ReceiveAndConvert()操作使用的默认转换策略是SimpleMessageConverter类。

The SimpleMessageConverter is able to handle TextMessages, BytesMessages, MapMessages, and ObjectMessages. This class implements the MessageConverter interface.

SimpleMessageConverter能够处理TextMessages、BytesMessages、MapMessages，以及ObjectMessages。该类实现了MessageConverter 接口。

Apart from SimpleMessageConverter, Spring JMS provides some other MessageConverter classes out of the box like MappingJackson2MessageConverter, MarshallingMessageConverter, MessagingMessageConverter.

除了SimpleMessageConverter，Spring JMS还提供了其他一些MessageConverter类，如MappingJackson2MessageConverter、MarshallingMessageConverter、MessagingMessageConverter。

Moreover, we can create custom message conversion functionality simply by implementing the MessageConverter interface’s toMessage() and FromMessage() methods.

此外，我们可以通过实现MessageConverter接口的toMessage()和FromMessage()方法来创建自定义消息转换功能。

Let us see a sample code snippet on implementing a custom MessageConverter,

让我们看看实现自定义MessageConverter的示例代码片断。

public class SampleMessageConverter implements MessageConverter {
    public Object fromMessage(Message message) 
      throws JMSException, MessageConversionException {
        //...
    }

    public Message toMessage(Object object, Session session)
      throws JMSException, MessageConversionException { 
        //...
    }
}

7. Sample Spring JMS

7.Spring JMS的样本

In this section, we will see how to use a JmsTemplate to send and receive messages.

在本节中，我们将看到如何使用JmsTemplate来发送和接收消息。

The default method for sending the message is JmsTemplate.send(). It has two key parameters of which, the first parameter is the JMS destination and the second parameter is an implementation of MessageCreator. The JmsTemplate uses the MessageCreator‘s callback method createMessage() for constructing the message.

发送消息的默认方法是JmsTemplate.send()。它有两个关键参数，其中第一个参数是JMS目的地，第二个参数是MessageCreator的实现。JmsTemplate使用MessageCreator的回调方法createMessage()来构建消息。

JmsTemplate.send() is good for sending plain text messages but in order to send custom messages, JmsTemplate has another method called convertAndSend().

JmsTemplate.send()适合发送纯文本信息，但为了发送自定义信息，JmsTemplate有另一个方法，叫做convertAndSend()。

We can see below the implementation of these methods:

我们可以在下面看到这些方法的实现。

public class SampleJmsMessageSender {

    private JmsTemplate jmsTemplate;
    private Queue queue;

    // setters for jmsTemplate & queue

    public void simpleSend() {
        jmsTemplate.send(queue, s -> s.createTextMessage("hello queue world"));
    }
    public void sendMessage(Employee employee) { 
        System.out.println("Jms Message Sender : " + employee); 
        Map<String, Object> map = new HashMap<>(); 
        map.put("name", employee.getName()); map.put("age", employee.getAge()); 
        jmsTemplate.convertAndSend(map); 
    }
}

Below is the message receiver class, we call it as Message-Driven POJO (MDP). We can see that the class SampleListener is implementing the MessageListener interface and provides the text specific implementation for the interface method onMessage().

下面是消息接收器类，我们称它为消息驱动的POJO（MDP）。我们可以看到SampleListener类正在实现MessageListener接口，并为接口方法onMessage()提供具体的文本实现。

Apart from onMessage() method, our SampleListener class also called a method receiveAndConvert() for receiving custom messages:

除了onMessage()方法，我们的SampleListener类也调用了一个方法receiveAndConvert()，用于接收自定义消息。

public class SampleListener implements MessageListener {

    public JmsTemplate getJmsTemplate() {
        return getJmsTemplate();
    }

    public void onMessage(Message message) {
        if (message instanceof TextMessage) {
            try {
                String msg = ((TextMessage) message).getText();
                System.out.println("Message has been consumed : " + msg);
            } catch (JMSException ex) {
                throw new RuntimeException(ex);
            }
        } else {
            throw new IllegalArgumentException("Message Error");
        }
    }

    public Employee receiveMessage() throws JMSException {
        Map map = (Map) getJmsTemplate().receiveAndConvert();
        return new Employee((String) map.get("name"), (Integer) map.get("age"));
    }
}

We saw how to implement MessageListener and below we see the configuration in Spring application context:

我们看到了如何实现MessageListener，下面我们看到Spring应用上下文中的配置。

<bean id="messageListener" class="com.baeldung.spring.jms.SampleListener" /> 

<bean id="jmsContainer" 
  class="org.springframework.jms.listener.DefaultMessageListenerContainer"> 
    <property name="connectionFactory" ref="connectionFactory"/> 
    <property name="destinationName" ref="IN_QUEUE"/> 
    <property name="messageListener" ref="messageListener" /> 
</bean>

DefaultMessageListenerContainer is the default message listener container Spring provides along with many other specialized containers.

DefaultMessageListenerContainer是Spring提供的默认消息监听器容器，同时还有许多其他专门的容器。

8. Basic Configuration With Java Annotations

8.使用Java注释的基本配置

The @JmsListener is the only annotation required to convert a method of a normal bean into a JMS listener endpoint. Spring JMS provides many more annotations to ease the JMS implementation.

@JmsListener是将普通Bean的方法转换为JMS监听器端点所需的唯一注解。Spring JMS提供了更多的注解来简化JMS的实现。

We can see some of the sample classes annotated below:

我们可以看到下面的一些例子类的注释。

@JmsListener(destination = "myDestination")
public void SampleJmsListenerMethod(Message<Order> order) { ... }

In order to add multiple listeners to a single method we just need to add multiple @JmsListener annotations.

为了给一个方法添加多个监听器，我们只需要添加多个@JmsListener注解。

We need to add the @EnableJms annotation to one of our configuration classes to support the @JmsListener annotated methods:

我们需要将@EnableJms注解添加到我们的一个配置类中，以支持@JmsListener注解的方法：。

@Configuration
@EnableJms
public class AppConfig {

    @Bean
    public DefaultJmsListenerContainerFactory jmsListenerContainerFactory() {
        DefaultJmsListenerContainerFactory factory 
          = new DefaultJmsListenerContainerFactory();
        factory.setConnectionFactory(connectionFactory());
        return factory;
    }
}

9. Error Handler

9.错误处理程序

We can also configure a custom error handler for our message listener container.

我们还可以为我们的消息监听器容器配置一个自定义错误处理程序。

Let’s first implement the org.springframework.util.ErrorHandler interface:

让我们首先实现org.springframework.util.ErrorHandler接口。

@Service
public class SampleJmsErrorHandler implements ErrorHandler {

    // ... logger

    @Override
    public void handleError(Throwable t) {
        LOG.warn("In default jms error handler...");
        LOG.error("Error Message : {}", t.getMessage());
    }

}

Note that we have overridden the handleError() method, which simply logs the error message.

请注意，我们已经覆盖了 handleError()方法，它只是记录了错误信息。

And then, we need to reference our error handler service in the DefaultJmsListenerConnectionFactory using the setErrorHandler() method:

然后，我们需要在DefaultJmsListenerConnectionFactory 中使用setErrorHandler() 方法引用我们的错误处理服务。

@Bean
public DefaultJmsListenerContainerFactorybjmsListenerContainerFactory() {
    DefaultJmsListenerContainerFactory factory 
      = new DefaultJmsListenerContainerFactory();
    factory.setConnectionFactory(connectionFactory());
    factory.setErrorHandler(sampleJmsErrorHandler);
    return factory;
}

With this, our configured error handler will now catch any unhandled exceptions and log the message. 

这样一来，我们配置的错误处理程序现在将捕获任何未处理的异常并记录信息。

Optionally, we can also configure the error handler using the plain-old XML configurations by updating our appContext.xml:

作为选择，我们也可以通过更新我们的 appContext.xml：，使用普通的XML配置来配置错误处理器。

<bean id="sampleJmsErrorHandler"
  class="com.baeldung.spring.jms.SampleJmsErrorHandler" />

<bean id="jmsContainer"
  class="org.springframework.jms.listener.DefaultMessageListenerContainer">
    <property name="connectionFactory" ref="connectionFactory" />
    <property name="destinationName" value="IN_QUEUE" />
    <property name="messageListener" ref="messageListener" />
    <property name="errorHandler" ref="sampleJmsErrorHandler" />
</bean>

10. Conclusion

10.结论

In this tutorial, we discussed the configuration and basic concepts of Spring JMS. We also had a brief look at the Spring-specific JmsTemplate classes which are used for sending and receiving messages.

在本教程中，我们讨论了Spring JMS的配置和基本概念。我们还简要介绍了Spring特有的JmsTemplate类，它用于发送和接收消息。

You can find the code implementation in the GitHub project.

你可以在GitHub项目中找到代码实现。