RabbitMQ Java客户端API指南

本指导覆盖了Java客户端api,它不仅仅是一个教程，在不同的部分都是可用的。
此java客户端得到了下面三方的许可

• Apache Public License 2.0
• Mozilla Public License
• GPL 2.0

概要

RabbitMQ java客户端使用 com.rabbitmq.client 作为最基础的包。主要的类和接口定义如下:

Channel（通道）
Connection
ConnectionFactory
Consumer

Channel接口主要用于协议的操作。Connection用于打开Channels、注册connection生命周期事件的管理者以及用来关闭不再使用的connections。ConnectionFactory用于实例化Connection，你也可以用它配置连接的各种设置，比如虚拟主机和用户名。

Connections and Channels

核心的api类是Connections 和Channels,分别代表一个AMQP 0-9-1协议的连接和一个通道，一般在使用他们之前你要像下面这样引用：

import com.rabbitmq.client.Connection; import com.rabbitmq.client.Channel;

一、连接主机
下面的代码将使用给定的参数一个主机（主机名、端口号等）：

ConnectionFactory factory = new ConnectionFactory();factory.setUsername(userName);factory.setPassword(password);factory.setVirtualHost(virtualHost);factory.setHost(hostName);factory.setPort(portNumber);Connection conn = factory.newConnection();

二、如果你在本地使用RabbitMQ服务器，上面的这些参数都有合理的默认值。
另外，你也可以使用URIs达到同样的功能

ConnectionFactory factory = new ConnectionFactory();factory.setUri("amqp://userName:password@hostName:portNumber/virtualHost");Connection conn = factory.newConnection();

三、如果你在本地使用一个stock的RabbitMQ服务器(不懂stock是什么意思)，上面的这些参数都有合理的默认值。
Connection 接口在创建完成后，可以用来打开一个通道.

Channel channel = conn.createChannel();

四、这个通道可以被用来发送和接收消息，如下面的章节描述。
如果你要断开连接(Connection )，只需关闭通道和连接即可。

channel.close();conn.close();

注意: 关闭通道是一个好的习惯，但是不是必需的。当你关闭连接时，通道会自动关闭的。

五、使用交换和队列（Using Exchanges and Queues）
客户端应用使用交换机和队列,这是使用AMQP协议的最高层次。他们必须在使用前声明。 声明任一类型的对象只是确保该对象的存在，如果有必要创建它吧。

channel.exchangeDeclare(exchangeName, "direct", true);String queueName = channel.queueDeclare().getQueue();channel.queueBind(queueName, exchangeName, routingKey); 

这将显式的声明以下对象，这两者都可以通过使用额外的参数来创建。在这里，他们都没有特殊的参数。

a durable, non-autodelete exchange of “direct” type a non-durable, exclusive, autodelete queue with a generated name

上述的queueBind函数用于绑定交换机和给定的路由关键字(routingKey)。

六、注意:上面是一个典型的声明一个队列的方式，当只有一个客户端使用它时。它不必使用一个公开的名字，没有其它客户可以使用它（独占模式），并且将被自动清理（自动删除）；如果几个客户端想要共享一个队列，必须使用下面的代码：

channel.exchangeDeclare(exchangeName, "direct", true);channel.queueDeclare(queueName, true, false, false, null);channel.queueBind(queueName, exchangeName, routingKey);

这将会显式的声明：

a durable, non-autodelete exchange of “direct” type a durable, non-exclusive, non-autodelete queue with a well-known name

注意：所有的关于通道的API方法可以被重载。为了使用方便，exchangeDeclare方法、queueDeclare方法和queueBind方法都提供默认值。如果有必要你可以使用更多的参数去重载他们，这给你提供了跟多的选择。
这种模式贯穿整个客户端API.

Publishing messages（发布消息）

七、信息的交换，使用channel.basicpublish如下：

byte[] messageBodyBytes = "Hello, world!".getBytes();channel.basicPublish(exchangeName, routingKey, null, messageBodyBytes);

八、对于一个控制，可以使用重载的变体来指定强制标志，或发送具有预先设置的消息属性的消息：

channel.basicPublish(exchangeName, routingKey, mandatory,                     MessageProperties.PERSISTENT_TEXT_PLAIN,                     messageBodyBytes);

九、以传递模式2（持久性）、优先级1和内容类型“文本/纯”发送消息。可以使用一个生成器类来创建自己的消息属性对象，如您所喜欢的属性，例如：

channel.basicPublish(exchangeName, routingKey,             new AMQP.BasicProperties.Builder()               .contentType("text/plain")               .deliveryMode(2)               .priority(1)               .userId("bob")               .build()),               messageBodyBytes);

十、此示例使用自定义标头发布消息：

Map<String, Object> headers = new HashMap<String, Object>();headers.put("latitude",  51.5252949);headers.put("longitude", -0.0905493);channel.basicPublish(exchangeName, routingKey,             new AMQP.BasicProperties.Builder()               .headers(headers)               .build()),               messageBodyBytes);

十一、此示例发布过期消息：

channel.basicPublish(exchangeName, routingKey,             new AMQP.BasicProperties.Builder()               .expiration("60000")               .build()),               messageBodyBytes);

十二、通道和并发考虑（线程安全模式）

通道实例不能再线程间共享。应用应该对每一个线程使用一个通道，而不是在线程间共享同一通道。渠道的操作有些事是安全的并发调用，有些不是，将会会导致线路上的不正确的帧交错。线程之间共享通道也将干扰确认发布消息者。

通过订阅接收消息

import com.rabbitmq.client.Consumer;import com.rabbitmq.client.DefaultConsumer;

接收消息最有效的方式是通过Consumer接口设置一个订阅。那么消息将会自定的送达，而不是明确的被请求。