RabbitMQ java API中文翻译

java客户端api指导

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

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

你可以通过查看javadoc文档来得到更多的信息。
此java客户端还附带一些命令行工具。
客户端api严格遵守AMQP-9-1协议的规范，并提供了额外的抽象便于使用。

概要

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;

Connecting to a broker

下面的代码用于连接一个AMQP协议的broker(代理服务器)，可以使用给定的参数列表(主机名，端口号等)

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);

你也可以指定mandatory标志或者使用预先设定的消息属性，如下:

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

你也可以使用发送模式参数为2（持久的），优先级为1，内容类型为text/plain。你也可以自定义消息发送属性对象，利用一个创建类，如下：

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

下面的例子使用自定义的头发送消息

Map headers = new HashMap();
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);

我们在这里并没有举出所有的例子。
注意：BasicProperties是一个自动生成的AMQP协议的内部类。如果资源驱动的警报(resource-driven alarm)被触发，basicPublish方法将被阻塞。

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

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

通过订阅接收消息

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

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

(未完待续)