使用方法详细信息

1. createTopic

   public void createTopic(String key, String newTopic, int queueNum)

   在broker上创建一个topic。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     key	String	是			访问密钥。
     newTopic	String	是			新建topic的名称。由数字、字母、下划线（_）、横杠（-）、竖线（|）或百分号（%）组成； 长度小于255；不能为TBW102或空。
     queueNum	int	是	0	(0, maxIntValue]	topic的队列数量。

   • 返回值描述：

     void

   • 异常描述：

     MQClientException - 生产者状态非Running；未找到broker等客户端异常。

2. createTopic

   public void createTopic(String key, String newTopic, int queueNum, int topicSysFlag)

   在broker上创建一个topic。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     key	String	是			访问密钥。
     newTopic	String	是			新建topic的名称。
     queueNum	int	是	0	(0, maxIntValue]	topic的队列数量。
     topicSysFlag	int	是	0		保留字段，暂未使用。

   • 返回值描述：

     void

   • 异常描述：

     MQClientException - 生产者状态非Running；未找到broker等客户端异常。

3. earliestMsgStoreTime

   public long earliestMsgStoreTime(MessageQueue mq)

   查询最早的消息存储时间。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     mq	MessageQueue	是			要查询的消息队列

   • 返回值描述：

     指定队列最早的消息存储时间。单位：毫秒。

   • 异常描述：

     MQClientException - 生产者状态非Running；没有找到broker；broker返回失败；网络异常；线程中断等客户端异常。

4. fetchPublishMessageQueues

   public List<MessageQueue> fetchPublishMessageQueues(String topic)

   获取topic的消息队列。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     topic	String	是			topic名称

   • 返回值描述：

     传入topic下的消息队列。

   • 异常描述：

     MQClientException - 生产者状态非Running；没有找到broker；broker返回失败；网络异常；线程中断等客户端异常。

5. maxOffset

   public long maxOffset(MessageQueue mq)

   查询消息队列的最大物理偏移量。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     mq	MessageQueue	是			要查询的消息队列

   • 返回值描述：

     给定消息队列的最大物理偏移量。

   • 异常描述：

     MQClientException - 生产者状态非Running；没有找到broker；broker返回失败；网络异常；线程中断等客户端异常。

6. minOffset

   public long minOffset(MessageQueue mq)

   查询给定消息队列的最小物理偏移量。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     mq	MessageQueue	是			要查询的消息队列

   • 返回值描述：

     给定消息队列的最小物理偏移量。

   • 异常描述：

     MQClientException - 生产者状态非Running；没有找到broker；broker返回失败；网络异常；线程中断等客户端异常。

7. queryMessage

   public QueryResult queryMessage(String topic, String key, int maxNum, long begin, long end)

   按关键字查询消息。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     topic	String	是			topic名称
     key	String	否	null		查找的关键字
     maxNum	int	是			返回消息的最大数量
     begin	long	是			开始时间戳，单位：毫秒
     end	long	是			结束时间戳，单位：毫秒

   • 返回值描述：

     查询到的消息集合。

   • 异常描述：

     MQClientException - 生产者状态非Running；没有找到broker；broker返回失败；网络异常等客户端异常客户端异常。
     InterruptedException - 线程中断。

8. searchOffset

   public long searchOffset(MessageQueue mq, long timestamp)

   查找指定时间的消息队列的物理偏移量。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     mq	MessageQueue	是			要查询的消息队列。
     timestamp	long	是			指定要查询时间的时间戳。单位：毫秒。

   • 返回值描述：

     指定时间的消息队列的物理偏移量。

   • 异常描述：

     MQClientException - 生产者状态非Running；没有找到broker；broker返回失败；网络异常；线程中断等客户端异常。

9. send

   public SendResult send(Collection<Message> msgs)

   同步批量发送消息。在返回发送失败之前，内部尝试重新发送消息的最大次数（参见retryTimesWhenSendFailed属性）。未明确指定发送队列，默认采取轮询策略发送。

   • 入参描述：

     参数名	类型	是否必须	默认值	值范围	说明
     msgs	Collection	是			待发送的消息集合。集合内的消息必须属同一个topic。

   • 返回值描述：

     批量消息的发送结果，包含msgId，发送状态等信息。

   • 异常描述：

     MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
     RemotingException - 网络异常。
     MQBrokerException - broker发生错误。
     InterruptedException - 发送线程中断。
     RemotingTooMuchRequestException - 发送超时。

10. send

    public SendResult send(Collection<Message> msgs, long timeout)

    同步批量发送消息，如果在指定的超时时间内未完成消息投递，会抛出RemotingTooMuchRequestException。 在返回发送失败之前，内部尝试重新发送消息的最大次数（参见retryTimesWhenSendFailed属性）。未明确指定发送队列，默认采取轮询策略发送。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msgs	Collection	是			待发送的消息集合。集合内的消息必须属同一个topic。
      timeout	long	是	参见sendMsgTimeout属性		发送超时时间，单位：毫秒。

    • 返回值描述：

      批量消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

11. send

    public SendResult send(Collection<Message> msgs, MessageQueue messageQueue)

    向给定队列同步批量发送消息。

    注意：指定队列意味着所有消息均为同一个topic。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msgs	Collection	是			待发送的消息集合。集合内的消息必须属同一个topic。
      messageQueue	MessageQueue	是			待投递的消息队列。指定队列意味着待投递消息均为同一个topic。

    • 返回值描述：

      批量消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

12. send

    public SendResult send(Collection<Message> msgs, MessageQueue messageQueue, long timeout)

    向给定队列同步批量发送消息，如果在指定的超时时间内未完成消息投递，会抛出RemotingTooMuchRequestException。

    注意：指定队列意味着所有消息均为同一个topic。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msgs	Collection	是			待发送的消息集合。集合内的消息必须属同一个topic。
      timeout	long	是	参见sendMsgTimeout属性		发送超时时间，单位：毫秒。
      messageQueue	MessageQueue	是			待投递的消息队列。指定队列意味着待投递消息均为同一个topic。

    • 返回值描述：

      批量消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

13. send

    public SendResult send(Message msg)

    以同步模式发送消息，仅当发送过程完全完成时，此方法才会返回。 在返回发送失败之前，内部尝试重新发送消息的最大次数（参见retryTimesWhenSendFailed属性）。未明确指定发送队列，默认采取轮询策略发送。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。

    • 返回值描述：

      消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

14. send

    public SendResult send(Message msg, long timeout)

    以同步模式发送消息，如果在指定的超时时间内未完成消息投递，会抛出RemotingTooMuchRequestException。仅当发送过程完全完成时，此方法才会返回。 在返回发送失败之前，内部尝试重新发送消息的最大次数（参见retryTimesWhenSendFailed属性）。未明确指定发送队列，默认采取轮询策略发送。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      timeout	long	是	参见sendMsgTimeout属性		发送超时时间，单位：毫秒。

    • 返回值描述：

      消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

15. send

    public SendResult send(Message msg, MessageQueue mq)

    向指定的消息队列同步发送单条消息。仅当发送过程完全完成时，此方法才会返回。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      mq	MessageQueue	是			待投递的消息队列。

    • 返回值描述：

      消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

16. send

    public SendResult send(Message msg, MessageQueue mq, long timeout)

    向指定的消息队列同步发送单条消息，如果在指定的超时时间内未完成消息投递，会抛出RemotingTooMuchRequestException。仅当发送过程完全完成时，此方法才会返回。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      timeout	long	是	参见sendMsgTimeout属性		发送超时时间，单位：毫秒。
      mq	MessageQueue	是			待投递的消息队列。指定队列意味着待投递消息均为同一个topic。

    • 返回值描述：

      消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

17. send

    public void send(Message msg, MessageQueue mq, SendCallback sendCallback)

    向指定的消息队列异步发送单条消息，异步发送调用后直接返回，并在在发送成功或者异常时回调sendCallback，所以异步发送时sendCallback参数不能为null，否则在回调时会抛出NullPointerException。 异步发送时，在成功发送前，其内部会尝试重新发送消息的最大次数（参见retryTimesWhenSendAsyncFailed属性）。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      mq	MessageQueue	是			待投递的消息队列。指定队列意味着待投递消息均为同一个topic。
      sendCallback	SendCallback	是			回调接口的实现。

    • 返回值描述：

      void

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

18. send

    public void send(Message msg, MessageQueue mq, SendCallback sendCallback, long timeout)

    向指定的消息队列异步发送单条消息，异步发送调用后直接返回，并在在发送成功或者异常时回调sendCallback，所以异步发送时sendCallback参数不能为null，否则在回调时会抛出NullPointerException。 若在指定时间内消息未发送成功，回调方法会收到RemotingTooMuchRequestException异常。 异步发送时，在成功发送前，其内部会尝试重新发送消息的最大次数（参见retryTimesWhenSendAsyncFailed属性）。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      mq	MessageQueue	是			待投递的消息队列。
      sendCallback	SendCallback	是			回调接口的实现。
      timeout	long	是	参见sendMsgTimeout属性		发送超时时间，单位：毫秒。

    • 返回值描述： void

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

19. send

    public SendResult send(Message msg, MessageQueueSelector selector, Object arg)

    向通过MessageQueueSelector计算出的队列同步发送消息。

    可以通过自实现MessageQueueSelector接口，将某一类消息发送至固定的队列。比如：将同一个订单的状态变更消息投递至固定的队列。

    注意：此消息发送失败内部不会重试。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      selector	MessageQueueSelector	是			队列选择器。
      arg	Object	否			供队列选择器使用的参数对象。

    • 返回值描述：

      消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

20. send

    public SendResult send(Message msg, MessageQueueSelector selector, Object arg, long timeout)

    向通过MessageQueueSelector计算出的队列同步发送消息，并指定发送超时时间。

    可以通过自实现MessageQueueSelector接口，将某一类消息发送至固定的队列。比如：将同一个订单的状态变更消息投递至固定的队列。

    注意：此消息发送失败内部不会重试。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      selector	MessageQueueSelector	是			队列选择器。
      arg	Object	否			供队列选择器使用的参数对象。
      timeout	long	是	参见sendMsgTimeout属性		发送超时时间，单位：毫秒。

    • 返回值描述：

      消息的发送结果，包含msgId，发送状态等信息。

    • 异常描述： MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      MQBrokerException - broker发生错误。
      InterruptedException - 发送线程中断。
      RemotingTooMuchRequestException - 发送超时。

21. send

    public void send(Message msg, MessageQueueSelector selector, Object arg, SendCallback sendCallback)

    向通过MessageQueueSelector计算出的队列异步发送单条消息，异步发送调用后直接返回，并在在发送成功或者异常时回调sendCallback，所以异步发送时sendCallback参数不能为null，否则在回调时会抛出NullPointerException。 异步发送时，在成功发送前，其内部会尝试重新发送消息的最大次数（参见retryTimesWhenSendAsyncFailed属性）。

    可以通过自实现MessageQueueSelector接口，将某一类消息发送至固定的队列。比如：将同一个订单的状态变更消息投递至固定的队列。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      selector	MessageQueueSelector	是			队列选择器。
      arg	Object	否			供队列选择器使用的参数对象。
      sendCallback	SendCallback	是			回调接口的实现。

    • 返回值描述：

      void

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

22. send

    public void send(Message msg, MessageQueueSelector selector, Object arg, SendCallback sendCallback, long timeout)

    向通过MessageQueueSelector计算出的队列异步发送单条消息，异步发送调用后直接返回，并在在发送成功或者异常时回调sendCallback，所以异步发送时sendCallback参数不能为null，否则在回调时会抛出NullPointerException。 异步发送时，在成功发送前，其内部会尝试重新发送消息的最大次数（参见retryTimesWhenSendAsyncFailed属性）。

    可以通过自实现MessageQueueSelector接口，将某一类消息发送至固定的队列。比如：将同一个订单的状态变更消息投递至固定的队列。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      selector	MessageQueueSelector	是			队列选择器。
      arg	Object	否			供队列选择器使用的参数对象。
      sendCallback	SendCallback	是			回调接口的实现。
      timeout	long	是	参见sendMsgTimeout属性		发送超时时间，单位：毫秒。

    • 返回值描述：

      void

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

23. send

    public void send(Message msg, SendCallback sendCallback)

    异步发送单条消息，异步发送调用后直接返回，并在在发送成功或者异常时回调sendCallback，所以异步发送时sendCallback参数不能为null，否则在回调时会抛出NullPointerException。 异步发送时，在成功发送前，其内部会尝试重新发送消息的最大次数（参见retryTimesWhenSendAsyncFailed属性）。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      sendCallback	SendCallback	是			回调接口的实现。

    • 返回值描述：

      void

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

24. send

    public void send(Message msg, SendCallback sendCallback, long timeout)

    异步发送单条消息，异步发送调用后直接返回，并在在发送成功或者异常时回调sendCallback，所以异步发送时sendCallback参数不能为null，否则在回调时会抛出NullPointerException。 异步发送时，在成功发送前，其内部会尝试重新发送消息的最大次数（参见retryTimesWhenSendAsyncFailed属性）。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      sendCallback	SendCallback	是			回调接口的实现。
      timeout	long	是	参见sendMsgTimeout属性		发送超时时间，单位：毫秒。

    • 返回值描述：

      void

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

25. sendMessageInTransaction

    public TransactionSendResult sendMessageInTransaction(Message msg, LocalTransactionExecuter tranExecuter, final Object arg)

    发送事务消息。该类不做默认实现，抛出RuntimeException异常。参见：TransactionMQProducer类。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待投递的事务消息
      tranExecuter	LocalTransactionExecuter	是			本地事务执行器。该类已过期，将在5.0.0版本中移除。请勿使用该方法。
      arg	Object	是			供本地事务执行程序使用的参数对象

    • 返回值描述：

      事务结果，参见：LocalTransactionState类。

    • 异常描述：

      RuntimeException - 永远抛出该异常。

26. sendMessageInTransaction

    public TransactionSendResult sendMessageInTransaction(Message msg, final Object arg)

    发送事务消息。该类不做默认实现，抛出RuntimeException异常。参见：TransactionMQProducer类。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待投递的事务消息
      arg	Object	是			供本地事务执行程序使用的参数对象

    • 返回值描述：

      事务结果，参见：LocalTransactionState类。

    • 异常描述：

      RuntimeException - 永远抛出该异常。

27. sendOneway

    public void sendOneway(Message msg)

    以oneway形式发送消息，broker不会响应任何执行结果，和UDP类似。它具有最大的吞吐量但消息可能会丢失。

    可在消息量大，追求高吞吐量并允许消息丢失的情况下使用该方式。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待投递的消息

    • 返回值描述：

      void

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

28. sendOneway

    public void sendOneway(Message msg, MessageQueue mq)

    向指定队列以oneway形式发送消息，broker不会响应任何执行结果，和UDP类似。它具有最大的吞吐量但消息可能会丢失。

    可在消息量大，追求高吞吐量并允许消息丢失的情况下使用该方式。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待投递的消息
      mq	MessageQueue	是			待投递的消息队列

    • 返回值描述： void

    • 异常描述： MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

29. sendOneway

    public void sendOneway(Message msg, MessageQueueSelector selector, Object arg)

    向通过MessageQueueSelector计算出的队列以oneway形式发送消息，broker不会响应任何执行结果，和UDP类似。它具有最大的吞吐量但消息可能会丢失。

    可在消息量大，追求高吞吐量并允许消息丢失的情况下使用该方式。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msg	Message	是			待发送的消息。
      selector	MessageQueueSelector	是			队列选择器。
      arg	Object	否			供队列选择器使用的参数对象。

    • 返回值描述：

      void

    • 异常描述：

      MQClientException - broker不存在或未找到；namesrv地址为空；未找到topic的路由信息等客户端异常。
      RemotingException - 网络异常。
      InterruptedException - 发送线程中断。

30. shutdown

    public void shutdown()

    关闭当前生产者实例并释放相关资源。

    • 入参描述：

      无。

    • 返回值描述：

      void

    • 异常描述：

31. start

    public void start()

    启动生产者实例。在发送或查询消息之前必须调用此方法。它执行了许多内部初始化，比如：检查配置、与namesrv建立连接、启动一系列心跳等定时任务等。

    • 入参描述：

      无。

    • 返回值描述：

      void

    • 异常描述：

      MQClientException - 初始化过程中出现失败。

32. viewMessage

    public MessageExt viewMessage(String offsetMsgId)

    根据给定的msgId查询消息。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      offsetMsgId	String	是			offsetMsgId

    • 返回值描述：

      返回MessageExt，包含：topic名称，消息题，消息ID，消费次数，生产者host等信息。

    • 异常描述：

      RemotingException - 网络层发生错误。
      MQBrokerException - broker发生错误。
      InterruptedException - 线程被中断。
      MQClientException - 生产者状态非Running；msgId非法等。

33. viewMessage

    public MessageExt viewMessage(String topic, String msgId)

    根据给定的msgId查询消息，并指定topic。

    • 入参描述：

      参数名	类型	是否必须	默认值	值范围	说明
      msgId	String	是			msgId
      topic	String	是			topic名称

    • 返回值描述：

      返回MessageExt，包含：topic名称，消息题，消息ID，消费次数，生产者host等信息。

    • 异常描述：

      RemotingException - 网络层发生错误。
      MQBrokerException - broker发生错误。
      InterruptedException - 线程被中断。
      MQClientException - 生产者状态非Running；msgId非法等。