使用 AMQ Spring Boot Starter
用于 AMQ 客户端 2.10
摘要
使开源包含更多
红帽承诺替换我们的代码、文档和网页属性中存在问题的语言。我们从这四个术语开始: master、slave、blacklist 和 whitelist。这些更改将在即将发行的几个发行本中逐渐实施。详情请查看 CTO Chris Wright 信息。
第 1 章 概述
AMQ Spring Boot Starter 是用于创建使用 AMQ 消息传递的基于 Spring 的应用的适配器。它提供了一个 Spring Boot starter 模块,供您构建独立的 Spring 应用。初学者使用 AMQ JMS 客户端通过 AMQP 1.0 协议进行通信。
AMQ Spring Boot Starter 是 AMQ 客户端的一部分,这是支持多种语言和平台的消息传递库套件。有关客户端的概述,请参阅 AMQ 客户端概述。有关此发行版本的详情,请参考 AMQ Clients 2.10 发行注记。
AMQ Spring Boot Starter 基于 AMQP 1.0 JMS Spring Boot 项目。
1.1. 主要特性
- 使用内置消息传递快速构建独立 Spring 应用程序
- 自动配置 JMS 资源
- 可配置 JMS 连接和会话池
1.2. 支持的标准和协议
- Spring Boot API 版本 2.2
- Java Message Service API 版本 2.0
- 高级消息队列协议( AMQP)版本 1.0
1.3. 支持的配置
有关 AMQ Spring Boot Starter 支持的配置,请参阅红帽客户门户网站中的 Red Hat AMQ 7 支持的配置。
1.4. 文档惯例
sudo 命令
在本文档中,sudo
用于任何需要 root 权限的命令。使用 sudo
时要小心,因为任何更改都可能会影响整个系统。有关 sudo
的详情请参考 使用 sudo 命令。
文件路径
在这个文档中,所有文件路径都对 Linux、UNIX 和类似操作系统有效(例如 /home/andrea
)。在 Microsoft Windows 中,您必须使用等效的 Windows 路径(例如 C:\Users\andrea
)。
变量文本
本文档包含代码块,它们需要使用特定于环境的值替换。变量文本括在箭头大括号内,样式为圆形单空间。例如,在以下命令中,将 <project-dir>
替换为您的环境的值:
$ cd <project-dir>
第 2 章 安装
本章指导您完成在您的环境中安装 AMQ Spring Boot Starter 的步骤。
2.1. 先决条件
- 您必须有 订阅 才能访问 AMQ 发行文件和存储库。
- 要使用 AMQ Spring Boot Starter 构建程序,您必须安装 Apache Maven。
- 要使用 AMQ Spring Boot Starter,您必须安装 Java。
2.2. 使用 Red Hat Maven 存储库
配置您的 Maven 环境,以从红帽 Maven 存储库下载客户端库。
流程
将红帽存储库添加到您的 Maven 设置或 POM 文件。如需示例配置文件,请参阅 第 B.1 节 “使用在线存储库”。
<repository> <id>red-hat-ga</id> <url>https://maven.repository.redhat.com/ga</url> </repository>
将库依赖关系添加到您的 POM 文件。
<dependency> <groupId>org.amqphub.spring</groupId> <artifactId>amqp-10-jms-spring-boot-starter</artifactId> <version>2.5.0.redhat-00001</version> </dependency>
该客户端现在在 Maven 项目中可用。
2.3. 安装本地 Maven 存储库
作为在线存储库的替代选择,可以将 AMQ Spring Boot Starter 作为基于文件的 Maven 存储库安装到本地文件系统中。
流程
- 使用您的订阅 下载 AMQ 客户端 2.10.0 Spring Boot Starter Maven 存储库 .zip 文件。
将文件内容提取到您选择的目录中。
在 Linux 或 UNIX 中,使用
unzip
命令提取文件内容。$ unzip amq-clients-2.10.0-spring-boot-starter-maven-repository.zip
在 Windows 上,右键单击 .zip 文件并选择" 提取所有"。
-
配置 Maven,以使用提取的安装目录中
maven-repository
目录中的存储库。如需更多信息,请参阅 第 B.2 节 “使用本地存储库”。
第 3 章 入门
本章将引导您完成设置环境并运行简单消息传递程序的步骤。
3.1. 先决条件
3.2. 运行 Hello World
Hello World 示例创建与代理的连接,发送一条包含问候语的消息到 example
队列,然后重新接收它。成功后,它会将收到的消息打印到控制台。
示例:发送并接收"Hello World!" - HelloWorld.java
package net.example; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.CommandLineRunner; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.jms.annotation.EnableJms; import org.springframework.jms.annotation.JmsListener; import org.springframework.jms.core.JmsTemplate; @EnableJms @SpringBootApplication public class HelloWorld implements CommandLineRunner { @Autowired private JmsTemplate jmsTemplate; public static void main(String[] args) { SpringApplication.run(HelloWorld.class, args); } @Override public void run(String... strings) throws Exception { sendMessage("Hello World!"); } public void sendMessage(String text) { System.out.println(String.format("Sending '%s'", text)); this.jmsTemplate.convertAndSend("example", text); } @JmsListener(destination = "example") public void receiveMessage(String text) { System.out.println(String.format("Received '%s'", text)); } }
运行示例
要编译并运行示例程序,请使用以下步骤:
流程
-
创建新项目目录。这在以下步骤中被称为
<project-dir>
。 将示例列表复制到以下位置:
<project-dir>/src/main/java/net/example/HelloWorld.java
使用文本编辑器创建新
<project-dir>/pom.xml
文件。在其中添加以下 XML:<project> <modelVersion>4.0.0</modelVersion> <groupId>net.example</groupId> <artifactId>example</artifactId> <version>1.0.0-SNAPSHOT</version> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.5.0</version> </parent> <dependencies> <dependency> <groupId>org.amqphub.spring</groupId> <artifactId>amqp-10-jms-spring-boot-starter</artifactId> <version>2.5.0.redhat-00001</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project>
更改到项目目录,并使用
mvn
命令编译该程序。$ mvn clean package
使用
java
命令来运行该程序。$ java -jar target/example-1.0.0-SNAPSHOT.jar
运行 Hello World 示例会导致以下控制台输出:
$ java -jar target/example-1.0.0-SNAPSHOT.jar . ____ _ __ _ _ /\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \ ( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \ \\/ ___)| |_)| | | | | || (_| | ) ) ) ) ' |____| .__|_| |_|_| |_\__, | / / / / =========|_|==============|___/=/_/_/_/ :: Spring Boot :: (v2.0.5.RELEASE) [...] 2018-11-05 16:21:09.849 INFO 14805 --- [main] net.example.HelloWorld: Started HelloWorld in 1.074 seconds (JVM running for 1.38) Sending 'Hello World!' Received 'Hello World!'
3.3. 其他示例
更多示例程序可从 AMQP 1.0 JMS Spring Boot 项目 和 Spring 项目 获取。
第 4 章 Configuration
在 application-properties
文件中可以使用以下选项来配置 Spring Boot 应用。
4.1. 连接选项
这些选项决定了 AMQ Spring Boot Starter 如何建立与远程 AMQP 对等点的连接。初学者使用 AMQ JMS 通过网络进行通信。如需更多信息,请参阅 使用 AMQ JMS 客户端。
- amqphub.amqp10jms.remoteUrl
AMQ JMS 客户端用于建立新连接的连接 URI。
连接 URI 格式
amqp[s]://host:port[?option=value[&option2=value...]]
如需更多信息,请参阅 使用 AMQ JMS 客户端 中的连接 URI。
- amqphub.amqp10jms.username
- 用于验证连接的用户名。
- amqphub.amqp10jms.password
- 用于验证连接的密码。
- amqphub.amqp10jms.clientId
- 应用到连接的客户端 ID。
- amqphub.amqp10jms.receiveLocalOnly
-
如果启用,则调用
receive
并带有超时参数,只检查消费者的本地消息缓冲。否则,还会检查远程对等点,以确保没有可用的消息。它默认是禁用的。 - amqphub.amqp10jms.receiveNoWaitLocalOnly
-
如果启用,调用
receiveNoWait
只检查消费者的本地信息缓冲。否则,还会检查远程对等点,以确保没有可用的消息。它默认是禁用的。
4.2. 池选项
这些选项决定了 AMQ Spring Boot Starter 如何缓存 JMS 连接和会话。初学者使用 AMQ JMS 池进行池化。如需更多信息,请参阅 使用 AMQ JMS 池库。
- amqphub.amqp10jms.pool.enabled
- 控制是否启用池。它默认是禁用的。
- amqphub.amqp10jms.pool.maxConnections
- 单个池的最大连接数。默认值为 1。
- amqphub.amqp10jms.pool.maxSessionsPerConnection
每个连接的最大会话数。默认值为 500。负值会删除任何限制。
如果超过限制,
createSession()
会根据配置来阻断或抛出异常。- amqphub.amqp10jms.pool.blockIfSessionPoolIsFull
如果启用,调用
createSession()
块直到会话在池中可用。它会被默认启用。如果没有可用的会话,则调用
createSession()
会抛出IllegalStateException
。- amqphub.amqp10jms.pool.blockIfSessionPoolIsFullTimeout
-
被阻断调用
createSession()
前的时间以毫秒为单位抛出IllegalStateException
。默认值为 -1,即永远调用块。 - amqphub.amqp10jms.pool.connectionIdleTimeout
- 当前没有贷款的连接前的时间(毫秒为单位)可以被从池中驱除。默认值为 30 秒。0 代表禁用超时。
- amqphub.amqp10jms.pool.connectionCheckInterval
- 定期检查已过期连接的时间(毫秒为单位)。默认值为 0,表示禁用检查。
- amqphub.amqp10jms.pool.useAnonymousProducers
如果启用,为所有对
createProducer()
的调用使用单个匿名 JMSMessageProducer
。它会被默认启用。在个别情况下,这种行为不可取。如果禁用,对
createProducer()
的每个调用都会产生新的MessageProducer
实例。- amqphub.amqp10jms.pool.explicitProducerCacheSize
-
如果不使用匿名制作者,JMS
Session
可以配置为使用显式目的地缓存特定数量的MessageProducer
对象。当创建与缓存制作者不匹配的新制作者时,缓存中最旧的条目将被驱除。 - amqphub.amqp10jms.pool.useProviderJMSContext
如果启用,使用底层 JMS 供应商的
JMSContext
类。它默认是禁用的。在正常操作中,池使用自己的通用
JMSContext
实现来包装来自池中的连接,而不使用提供程序实施。般实施可能会限制供应商实施。但是,启用后,来自JMSContext
API 的连接不会由池管理。
附录 A. 使用您的订阅
AMQ 通过软件订阅提供。要管理您的订阅,请访问红帽客户门户中的帐户。
A.1. 访问您的帐户
流程
- 转至 access.redhat.com。
- 如果您还没有帐户,请创建一个帐户。
- 登录到您的帐户。
A.2. 激活订阅
流程
- 转至 access.redhat.com。
- 导航到 My Subscriptions。
- 导航到 激活订阅 并输入您的 16 位激活号。
A.3. 下载发行文件
要访问 .zip、.tar.gz 和其他发布文件,请使用客户门户查找要下载的相关文件。如果您使用 RPM 软件包或 Red Hat Maven 存储库,则不需要这一步。
流程
- 打开浏览器并登录红帽客户门户网站 产品下载页面,网址为 access.redhat.com/downloads。
- 查找 INTEGRATION 类别中 的红帽 AMQ 条目。
- 选择所需的 AMQ 产品。此时会打开 Software Downloads 页面。
- 单击组件的 Download 链接。
A.4. 为系统注册软件包
要在 Red Hat Enterprise Linux 上安装此产品的 RPM 软件包,必须注册您的系统。如果您使用下载的发行文件,则不需要这一步。
流程
- 转至 access.redhat.com。
- 进入 Registration Assistant。
- 选择您的操作系统版本,再继续到下一页。
- 使用您的系统终端中列出的命令完成注册。
有关注册您的系统的更多信息,请参阅以下资源之一:
附录 B. 使用红帽 Maven 存储库
本节论述了如何在您的软件中使用红帽提供的 Maven 存储库。
B.1. 使用在线存储库
红帽维护一个中央 Maven 存储库,用于基于 Maven 的项目。如需更多信息,请参阅 存储库欢迎页面。
可以通过两种方式将 Maven 配置为使用 Red Hat 存储库:
将存储库添加到 Maven 设置中
这种配置方法适用于您的用户拥有的所有 Maven 项目,只要您的 POM 文件不覆盖存储库配置并启用包含的配置集。
流程
找到 Maven
settings.xml
文件。它通常位于用户主目录的.m2
目录中。如果文件不存在,请使用文本编辑器创建该文件。在 Linux 或 UNIX 中:
/home/<username>/.m2/settings.xml
在 Windows 中:
C:\Users\<username>\.m2\settings.xml
在
settings.xml
文件的profiles
元素中添加包含红帽存储库的新配置集,如下例所示:示例:包含 Red Hat 软件仓库的 Maven
settings.xml
文件<settings> <profiles> <profile> <id>red-hat</id> <repositories> <repository> <id>red-hat-ga</id> <url>https://maven.repository.redhat.com/ga</url> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>red-hat-ga</id> <url>https://maven.repository.redhat.com/ga</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> </profile> </profiles> <activeProfiles> <activeProfile>red-hat</activeProfile> </activeProfiles> </settings>
有关 Maven 配置的更多信息,请参阅 Maven 设置参考。
在您的 POM 文件中添加软件仓库
要在项目中直接配置存储库,请在 POM 文件的 repositories
元素中添加一个新的条目,如下例所示:
示例:包含 Red Hat 软件仓库的 Maven pom.xml
文件
<project> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>example-app</artifactId> <version>1.0.0</version> <repositories> <repository> <id>red-hat-ga</id> <url>https://maven.repository.redhat.com/ga</url> </repository> </repositories> </project>
有关 POM 文件配置的更多信息,请参阅 Maven POM 参考。
B.2. 使用本地存储库
红帽为其部分组件提供基于文件的 Maven 存储库。这些内容作为可下载存档提供,您可以提取到本地文件系统。
要将 Maven 配置为使用本地提取的存储库,请在 Maven 设置或 POM 文件中应用以下 XML:
<repository>
<id>red-hat-local</id>
<url>${repository-url}</url>
</repository>
${repository-url}
必须是包含提取仓库本地文件系统路径的文件 URL。
操作系统 | 文件系统路径 | URL |
---|---|---|
Linux 或 UNIX |
|
|
Windows |
|
|
附录 C. 将 AMQ Broker 与示例搭配使用
AMQ Spring Boot Starter 示例需要一个正在运行的消息代理,其中包含名为 example
的队列。使用以下步骤安装和启动代理并定义队列。
C.1. 安装代理
按照 AMQ Broker 入门 以 安装代理 并创建代理 实例 中的内容进行操作。启用匿名访问。
以下步骤将代理实例的位置称为 <broker-instance-dir>
。
C.2. 启动代理
流程
使用
artemis run
命令启动代理。$ <broker-instance-dir>/bin/artemis run
检查控制台输出中是否有启动过程中记录的严重错误。代理日志记录
Server is now live
(当它就绪时)。$ example-broker/bin/artemis run __ __ ____ ____ _ /\ | \/ |/ __ \ | _ \ | | / \ | \ / | | | | | |_) |_ __ ___ | | _____ _ __ / /\ \ | |\/| | | | | | _ <| '__/ _ \| |/ / _ \ '__| / ____ \| | | | |__| | | |_) | | | (_) | < __/ | /_/ \_\_| |_|\___\_\ |____/|_| \___/|_|\_\___|_| Red Hat AMQ <version> 2020-06-03 12:12:11,807 INFO [org.apache.activemq.artemis.integration.bootstrap] AMQ101000: Starting ActiveMQ Artemis Server ... 2020-06-03 12:12:12,336 INFO [org.apache.activemq.artemis.core.server] AMQ221007: Server is now live ...
C.3. 创建队列
在新终端中,使用 artemis queue
命令创建名为 example
的队列。
$ <broker-instance-dir>/bin/artemis queue create --name example --address example --auto-create-address --anycast
系统将提示您回答一系列"是"或无问题。对所有设备回答 N
。
队列创建后,代理就可与示例程序配合使用。
C.4. 停止代理
运行完示例后,使用 artemis stop
命令停止代理。
$ <broker-instance-dir>/bin/artemis stop
2021-08-31 15:44:40 +1000 修订