API_Reference_DefaultMQProducer.md 41.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088
## DefaultMQProducer
---
### 类简介

`public class DefaultMQProducer 
extends ClientConfig 
implements MQProducer`

>`DefaultMQProducer`类是应用用来投递消息的入口,开箱即用,可通过无参构造方法快速创建一个生产者。主要负责消息的发送,支持同步/异步/oneway的发送方式,这些发送方式均支持批量发送。可以通过该类提供的getter/setter方法,调整发送者的参数。`DefaultMQProducer`提供了多个send方法,每个send方法略有不同,在使用前务必详细了解其意图。下面给出一个生产者示例代码,[点击查看更多示例代码](https://github.com/apache/rocketmq/blob/master/example/src/main/java/org/apache/rocketmq/example/)。

``` java 
public class Producer {
    public static void main(String[] args) throws MQClientException {
        // 创建指定分组名的生产者
        DefaultMQProducer producer = new DefaultMQProducer("ProducerGroupName");

        // 启动生产者
        producer.start();

        for (int i = 0; i < 128; i++)
            try {
            	// 构建消息
                Message msg = new Message("TopicTest",
                        "TagA",
                        "OrderID188",
                        "Hello world".getBytes(RemotingHelper.DEFAULT_CHARSET));

                // 同步发送
                SendResult sendResult = producer.send(msg);

                // 打印发送结果
                System.out.printf("%s%n", sendResult);
            } catch (Exception e) {
                e.printStackTrace();
            }

        producer.shutdown();
    }
}
```

**注意**:该类是线程安全的。在配置并启动完成后可在多个线程间安全共享。

### 字段摘要
|类型|字段名称|描述|
|------|-------|-------|
|DefaultMQProducerImpl|defaultMQProducerImpl|生产者的内部默认实现|
|String|producerGroup|生产者分组|
|String|createTopicKey|在发送消息时,自动创建服务器不存在的topic|
|int|defaultTopicQueueNums|创建topic时默认的队列数量|
|int|sendMsgTimeout|发送消息的超时时间|
|int|compressMsgBodyOverHowmuch|压缩消息体的阈值|
|int|retryTimesWhenSendFailed|同步模式下内部尝试发送消息的最大次数|
|int|retryTimesWhenSendAsyncFailed|异步模式下内部尝试发送消息的最大次数|
|boolean|retryAnotherBrokerWhenNotStoreOK|是否在内部发送失败时重试另一个broker|
|int|maxMessageSize|消息的最大长度|
|TraceDispatcher|traceDispatcher|消息追踪器。使用rcpHook来追踪消息|

### 构造方法摘要

|方法名称|方法描述|
|-------|------------|
|DefaultMQProducer()|由默认参数值创建一个生产者 |
|DefaultMQProducer(final String producerGroup)|使用指定的分组名创建一个生产者|
|DefaultMQProducer(final String producerGroup, boolean enableMsgTrace)|使用指定的分组名创建一个生产者,并设置是否开启消息追踪|
|DefaultMQProducer(final String producerGroup, boolean enableMsgTrace, final String customizedTraceTopic)|使用指定的分组名创建一个生产者,并设置是否开启消息追踪及追踪topic的名称|
|DefaultMQProducer(RPCHook rpcHook)|使用指定的hook创建一个生产者|
|DefaultMQProducer(final String producerGroup, RPCHook rpcHook)|使用指定的分组名及自定义hook创建一个生产者|
|DefaultMQProducer(final String producerGroup, RPCHook rpcHook, boolean enableMsgTrace,final String customizedTraceTopic)|使用指定的分组名及自定义hook创建一个生产者,并设置是否开启消息追踪及追踪topic的名称|

### 使用方法摘要

|返回值|方法名称|方法描述|
|-------|-------|------------|
|void|createTopic(String key, String newTopic, int queueNum)|在broker上创建指定的topic|
|void|createTopic(String key, String newTopic, int queueNum, int topicSysFlag)|在broker上创建指定的topic|
|long|earliestMsgStoreTime(MessageQueue mq)|查询最早的消息存储时间|
|List<MessageQueue>|fetchPublishMessageQueues(String topic)|获取topic的消息队列|
|long|maxOffset(MessageQueue mq)|查询给定消息队列的最大offset|
|long|minOffset(MessageQueue mq)|查询给定消息队列的最小offset|
|QueryResult|queryMessage(String topic, String key, int maxNum, long begin, long end)|按关键字查询消息|
|long|searchOffset(MessageQueue mq, long timestamp)|查找指定时间的消息队列的物理offset|
|SendResult|send(Collection<Message> msgs)|同步批量发送消息|
|SendResult|send(Collection<Message> msgs, long timeout)|同步批量发送消息|
|SendResult|send(Collection<Message> msgs, MessageQueue messageQueue)|向指定的消息队列同步批量发送消息|
|SendResult|send(Collection<Message> msgs, MessageQueue messageQueue, long timeout)|向指定的消息队列同步批量发送消息,并指定超时时间|
|SendResult|send(Message msg)|同步单条发送消息|
|SendResult|send(Message msg, long timeout)|同步发送单条消息,并指定超时时间|
|SendResult|send(Message msg, MessageQueue mq)|向指定的消息队列同步发送单条消息|
|SendResult|send(Message msg, MessageQueue mq, long timeout)|向指定的消息队列同步单条发送消息,并指定超时时间|
|void|send(Message msg, MessageQueue mq, SendCallback sendCallback)|向指定的消息队列异步单条发送消息,并指定回调方法|
|void|send(Message msg, MessageQueue mq, SendCallback sendCallback, long timeout)|向指定的消息队列异步单条发送消息,并指定回调方法和超时时间|
|SendResult|send(Message msg, MessageQueueSelector selector, Object arg)|向消息队列同步单条发送消息,并指定发送队列选择器|
|SendResult|send(Message msg, MessageQueueSelector selector, Object arg, long timeout)|向消息队列同步单条发送消息,并指定发送队列选择器与超时时间|
|void|send(Message msg, MessageQueueSelector selector, Object arg, SendCallback sendCallback)|向指定的消息队列异步单条发送消息|
|void|send(Message msg, MessageQueueSelector selector, Object arg, SendCallback sendCallback, long timeout)|向指定的消息队列异步单条发送消息,并指定超时时间|
|void|send(Message msg, SendCallback sendCallback)|异步发送消息|
|void|send(Message msg, SendCallback sendCallback, long timeout)|异步发送消息,并指定回调方法和超时时间|
|TransactionSendResult|sendMessageInTransaction(Message msg, LocalTransactionExecuter tranExecuter, final Object arg)|发送事务消息,并指定本地执行事务实例|
|TransactionSendResult|sendMessageInTransaction(Message msg, Object arg)|发送事务消息|
|void|sendOneway(Message msg)|单向发送消息,不等待broker响应|
|void|sendOneway(Message msg, MessageQueue mq) |单向发送消息到指定队列,不等待broker响应|
|void|sendOneway(Message msg, MessageQueueSelector selector, Object arg)|单向发送消息到队列选择器的选中的队列,不等待broker响应|
|void|shutdown()|关闭当前生产者实例并释放相关资源|
|void|start()|启动生产者|
|MessageExt|viewMessage(String offsetMsgId)|根据给定的msgId查询消息|
|MessageExt|public MessageExt viewMessage(String topic, String msgId)|根据给定的msgId查询消息,并指定topic|

### 字段详细信息

- [producerGroup](http://rocketmq.apache.org/docs/core-concept/)

	`private String producerGroup`
	
	生产者的分组名称。相同的分组名称表明生产者实例在概念上归属于同一分组。这对事务消息十分重要,如果原始生产者在事务之后崩溃,那么broker可以联系同一生产者分组的不同生产者实例来提交或回滚事务。

	默认值:DEFAULT_PRODUCER

	注意: 由数字、字母、下划线、横杠(-)、竖线(|)或百分号组成;不能为空;长度不能超过255。

- defaultMQProducerImpl

	`protected final transient DefaultMQProducerImpl defaultMQProducerImpl`

	生产者的内部默认实现,在构造生产者时内部自动初始化,提供了大部分方法的内部实现。

- createTopicKey

	`private String createTopicKey = MixAll.AUTO_CREATE_TOPIC_KEY_TOPIC`

	在发送消息时,自动创建服务器不存在的topic,需要指定Key,该Key可用于配置发送消息所在topic的默认路由。

	默认值:TBW102

	建议:测试或者demo使用,生产环境下不建议打开自动创建配置。

- defaultTopicQueueNums

	`private volatile int defaultTopicQueueNums = 4`

	创建topic时默认的队列数量。

	默认值:4

- sendMsgTimeout

	`private int sendMsgTimeout = 3000`

	发送消息时的超时时间。

	默认值:3000,单位:毫秒 

	建议:不建议修改该值,该值应该与broker配置中的sendTimeout一致,发送超时,可临时修改该值,建议解决超时问题,提高broker集群的Tps。

- compressMsgBodyOverHowmuch

	`private int compressMsgBodyOverHowmuch = 1024 * 4`

	压缩消息体阈值。大于4K的消息体将默认进行压缩。

	默认值:1024 * 4,单位:字节

	建议:可通过DefaultMQProducerImpl.setZipCompressLevel方法设置压缩率(默认为5,可选范围[0,9]);可通过DefaultMQProducerImpl.tryToCompressMessage方法测试出compressLevel与compressMsgBodyOverHowmuch最佳值。

- retryTimesWhenSendFailed

	`private int retryTimesWhenSendFailed = 2`

	同步模式下,在返回发送失败之前,内部尝试重新发送消息的最大次数。

	默认值:2,即:默认情况下一条消息最多会被投递3次。

	注意:在极端情况下,这可能会导致消息的重复。

- retryTimesWhenSendAsyncFailed

	`private int retryTimesWhenSendAsyncFailed = 2`

	异步模式下,在发送失败之前,内部尝试重新发送消息的最大次数。

	默认值:2,即:默认情况下一条消息最多会被投递3次。

	注意:在极端情况下,这可能会导致消息的重复。

- retryAnotherBrokerWhenNotStoreOK

	`private boolean retryAnotherBrokerWhenNotStoreOK = false`

	同步模式下,消息保存失败时是否重试其他broker。

	默认值:false

	注意:此配置关闭时,非投递时产生异常情况下,会忽略retryTimesWhenSendFailed配置。

- maxMessageSize

	`private int maxMessageSize = 1024 * 1024 * 4`

	消息的最大大小。当消息题的字节数超过maxMessageSize就发送失败。

	默认值:1024 * 1024 * 4,单位:字节

- [traceDispatcher](https://github.com/apache/rocketmq/wiki/RIP-6-Message-Trace)

	`private TraceDispatcher traceDispatcher = null`

	在开启消息追踪后,该类通过hook的方式把消息生产者,消息存储的broker和消费者消费消息的信息像链路一样记录下来。在构造生产者时根据构造入参enableMsgTrace来决定是否创建该对象。

### 构造方法详细信息

1. DefaultMQProducer
	
	`public DefaultMQProducer()`

	创建一个新的生产者。

2. DefaultMQProducer
	
	`DefaultMQProducer(final String producerGroup)`

	使用指定的分组名创建一个生产者。

	- 入参描述:

		参数名 | 类型 | 是否必须 | 缺省值 |描述
		---|---|---|---|---
		producerGroup | String | 是 | DEFAULT_PRODUCER | 生产者的分组名称

3. DefaultMQProducer
	
	`DefaultMQProducer(final String producerGroup, boolean enableMsgTrace)`

	使用指定的分组名创建一个生产者,并设置是否开启消息追踪。

	- 入参描述:

		参数名 | 类型 | 是否必须 | 缺省值 |描述
		---|---|---|---|---
		producerGroup | String | 是 | DEFAULT_PRODUCER | 生产者的分组名称
		enableMsgTrace | boolean | 是 | false |是否开启消息追踪

4. DefaultMQProducer
	
	`DefaultMQProducer(final String producerGroup, boolean enableMsgTrace, final String customizedTraceTopic)`

	使用指定的分组名创建一个生产者,并设置是否开启消息追踪及追踪topic的名称。

	- 入参描述:

		参数名 | 类型 | 是否必须 | 缺省值 |描述
		---|---|---|---|---
		producerGroup | String | 是 | DEFAULT_PRODUCER | 生产者的分组名称
		rpcHook | RPCHook | 否 | null |每个远程命令执行后会回调rpcHook
		enableMsgTrace | boolean | 是 | false |是否开启消息追踪
		customizedTraceTopic | String | 否 | RMQ_SYS_TRACE_TOPIC | 消息跟踪topic的名称

5. DefaultMQProducer
	
	`DefaultMQProducer(RPCHook rpcHook)`

	使用指定的hook创建一个生产者。

	- 入参描述:

		参数名 | 类型 | 是否必须 | 缺省值 |描述
		---|---|---|---|---
		rpcHook | RPCHook | 否 | null |每个远程命令执行后会回调rpcHook

6. DefaultMQProducer

	`DefaultMQProducer(final String producerGroup, RPCHook rpcHook)`

	使用指定的分组名及自定义hook创建一个生产者。

	- 入参描述:

		参数名 | 类型 | 是否必须 | 缺省值 |描述
		---|---|---|---|---
		producerGroup | String | 是 | DEFAULT_PRODUCER | 生产者的分组名称
		rpcHook | RPCHook | 否 | null |每个远程命令执行后会回调rpcHook

7. DefaultMQProducer

	`DefaultMQProducer(final String producerGroup, RPCHook rpcHook, boolean enableMsgTrace,final String customizedTraceTopic)`

	使用指定的分组名及自定义hook创建一个生产者,并设置是否开启消息追踪及追踪topic的名称。

	- 入参描述:

	参数名 | 类型 | 是否必须 | 缺省值 |描述
	---|---|---|---|---
	producerGroup | String | 是 | DEFAULT_PRODUCER | 生产者的分组名称
	rpcHook | RPCHook | 否 | null |每个远程命令执行后会回调rpcHook
	enableMsgTrace | boolean | 是 | false |是否开启消息追踪
	customizedTraceTopic | String | 否 | RMQ_SYS_TRACE_TOPIC | 消息跟踪topic的名称

### 使用方法详细信息

1.  createTopic

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

	在broker上创建一个topic。

	- 入参描述:

		参数名 | 类型 | 是否必须 | 默认值 |值范围 | 说明
		---|---|---|---|---|---
		key | String | 是 | | | 访问密钥。
		newTopic | String | 是 | |  | 新建topic的名称。由数字、字母、下划线(_)、横杠(-)、竖线(&#124;)或百分号(%)组成;<br>长度小于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返回失败;网络异常等客户端异常客户端异常。<br>
		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<Message> | 是 | | | 待发送的消息集合。集合内的消息必须属同一个topic。

	- 返回值描述:

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

	- 异常描述:

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

10. send

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

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

	- 入参描述:
		
		参数名 | 类型 | 是否必须 | 默认值 | 值范围 | 说明
		---|---|---|---|---|---
		msgs | Collection<Message> | 是 | | | 待发送的消息集合。集合内的消息必须属同一个topic。
		timeout | long | 是 | 参见*sendMsgTimeout*属性 | | 发送超时时间,单位:毫秒。

	- 返回值描述:

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

	- 异常描述:

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

11. send

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

	向给定队列同步批量发送消息。
	
	注意:指定队列意味着所有消息均为同一个topic。

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

	- 返回值描述:

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

	- 异常描述:

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

12. send

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

	向给定队列同步批量发送消息,如果在指定的超时时间内未完成消息投递,会抛出*RemotingTooMuchRequestException*。
	
	注意:指定队列意味着所有消息均为同一个topic。

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

	- 返回值描述:

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

	- 异常描述:

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

13. send

	`public SendResult send(Message msg)`

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

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

	- 返回值描述:

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

	- 异常描述:

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

14. send

	`public SendResult send(Message msg, long timeout)`

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

	- 入参描述:
		
		参数名 | 类型 | 是否必须 | 默认值 | 值范围 | 说明
		---|---|---|---|---|---
		msg | Message | 是 | | | 待发送的消息。
		timeout | long | 是 | 参见*sendMsgTimeout*属性 | | 发送超时时间,单位:毫秒。

	- 返回值描述:

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

	- 异常描述:

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

15. send

	`public SendResult send(Message msg, MessageQueue mq)`

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

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

	- 返回值描述:

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

	- 异常描述:

		MQClientException - broker不存在或未找到;namesrv地址为空;未找到topic的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		MQBrokerException - broker发生错误。<br>
		InterruptedException - 发送线程中断。<br>
		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的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		MQBrokerException - broker发生错误。<br>
		InterruptedException - 发送线程中断。<br>
		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的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		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的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		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的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		MQBrokerException - broker发生错误。<br>
		InterruptedException - 发送线程中断。<br>
		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的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		MQBrokerException - broker发生错误。<br>
		InterruptedException - 发送线程中断。<br>
		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的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		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的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		InterruptedException - 发送线程中断。

23. send

	`public void send(Message msg, SendCallback sendCallback)`

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

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

	- 返回值描述:

		void

	- 异常描述:

		MQClientException - broker不存在或未找到;namesrv地址为空;未找到topic的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		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的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		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](https://en.wikipedia.org/wiki/User_Datagram_Protocol)类似。它具有最大的吞吐量但消息可能会丢失。

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

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

	- 返回值描述:
		
		void

	- 异常描述:

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

28. sendOneway

	`public void sendOneway(Message msg, MessageQueue mq)`

	  向指定队列以oneway形式发送消息,broker不会响应任何执行结果,和[UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol)类似。它具有最大的吞吐量但消息可能会丢失。

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

	- 入参描述:

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

	- 返回值描述:
		void
	- 异常描述:
		MQClientException - broker不存在或未找到;namesrv地址为空;未找到topic的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		InterruptedException - 发送线程中断。

29. sendOneway

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

	  向通过`MessageQueueSelector`计算出的队列以oneway形式发送消息,broker不会响应任何执行结果,和[UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol)类似。它具有最大的吞吐量但消息可能会丢失。

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

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

	- 返回值描述:
		
		void

	- 异常描述:

		MQClientException - broker不存在或未找到;namesrv地址为空;未找到topic的路由信息等客户端异常。<br>
		RemotingException - 网络异常。<br>
		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 - 网络层发生错误。<br>
		MQBrokerException - broker发生错误。<br>
		InterruptedException - 线程被中断。<br>
		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 - 网络层发生错误。<br>
		MQBrokerException - broker发生错误。<br>
		InterruptedException - 线程被中断。<br>
		MQClientException - 生产者状态非Running;msgId非法等。