update docs

README-zh.md

@@ -8,28 +8,33 @@ Spring Cloud Alibaba 致力于提供微服务开发的一站式解决方案。
 
 ## 主要功能
 
-* **服务限流降级**：默认支持 Servlet、RestTemplate、Dubbo 和 RocketMQ 限流降级功能的接入，可以在运行时通过控制台实时修改限流降级规则，还支持查看限流降级 Metrics 监控。
+* **服务限流降级**：默认支持 Servlet、Feign、RestTemplate、Dubbo 和 RocketMQ 限流降级功能的接入，可以在运行时通过控制台实时修改限流降级规则，还支持查看限流降级 Metrics 监控。
 * **服务注册与发现**：适配 Spring Cloud 服务注册与发现标准，默认集成了 Ribbon 的支持。
 * **分布式配置管理**：支持分布式系统中的外部化配置，配置更改时自动刷新。
+* **消息驱动能力**：基于 Spring Cloud Stream 为微服务应用构建消息驱动能力。
 * **阿里云对象存储**：阿里云提供的海量、安全、低成本、高可靠的云存储服务。支持在任何应用、任何时间、任何地点存储和访问任意类型的数据。
 
 
 更多功能请参考 [Roadmap](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/Roadmap-zh.md)。
 
-## 组件:
+## 组件
 
 **[Sentinel](https://github.com/alibaba/Sentinel)**：把流量作为切入点，从流量控制、熔断降级、系统负载保护等多个维度保护服务的稳定性。
 
 **[Nacos](https://github.com/alibaba/Nacos)**：一个更易于构建云原生应用的动态服务发现、配置管理和服务管理平台。
 
+**[RocketMQ](https://rocketmq.apache.org/)**：一款开源的分布式消息系统，基于高可用分布式集群技术，提供低延时的、高可靠的消息发布与订阅服务。
+
+**[AliCloud ACM](https://www.aliyun.com/product/acm)**：一款在分布式架构环境中对应用配置进行集中管理和推送的应用配置中心产品。
+
 **[AliCloud OSS](https://www.aliyun.com/product/oss)**: 阿里云对象存储服务（Object Storage Service，简称 OSS），是阿里云提供的海量、安全、低成本、高可靠的云存储服务。您可以在任何应用、任何时间、任何地点存储和访问任意类型的数据。
 
 更多组件请参考 [Roadmap](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/Roadmap-zh.md)。
 
 ## 如何构建
 
-* master 分支对应的是 Spring Boot 2.x，最低支持 JDK 1.8。
+* master 分支对应的是 Spring Cloud Finchley，最低支持 JDK 1.8。
-* 1.x 分支对应的是 Spring Boot 1.x，最低支持 JDK 1.7。
+* 1.x 分支对应的是 Spring Cloud Edgware，最低支持 JDK 1.7。
 
 Spring Cloud 使用 Maven 来构建，最快的使用方式是将本项目clone到本地，然后执行以下命令：
 
@@ -83,6 +88,8 @@ Example 列表：
 
 [Nacos Discovery Example](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/spring-cloud-alibaba-examples/nacos-example/nacos-discovery-example/readme-zh.md)
 
+[RocketMQ Example](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/spring-cloud-alibaba-examples/rocketmq-example/readme-zh.md)
+
 [AliCloud OSS Example](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/spring-cloud-alibaba-examples/oss-example/readme-zh.md)
 
 [AliCloud ANS Example](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/spring-cloud-alibaba-examples/ans-example/ans-provider-example/readme-zh.md)

README.md

@@ -6,7 +6,7 @@ See the [中文文档](https://github.com/spring-cloud-incubator/spring-cloud-al
 
 Spring Cloud Alibaba provides a one-stop solution for distributed application development. It contains all the components required to develop distributed applications, making it easy for you to develop your applications using Spring Cloud.
 
-With Spring Cloud Alibaba，you only need to add some annotations and a small amount of configurations to connect Spring Cloud applications to the distributed solutions of Alibaba, and build a distributed application system with Alibaba middleware.
+With Spring Cloud Alibaba, you only need to add some annotations and a small amount of configurations to connect Spring Cloud applications to the distributed solutions of Alibaba, and build a distributed application system with Alibaba middleware.
 
 
 ## Features
@@ -14,6 +14,7 @@ With Spring Cloud Alibaba，you only need to add some annotations and a small am
 * **Flow control and service degradation**：Flow control for HTTP services is supported by default. You can also customize flow control and service degradation rules using annotations. The rules can be changed dynamically.
 * **Service registration and discovery**：Service can be registered and clients can discover the instances using Spring-managed beans, auto integration Ribbon.
 * **Distributed configuration**：support for externalized configuration in a distributed system, auto refresh when configuration changes.
+* **Event-driven**：support for building highly scalable event-driven microservices connected with shared messaging systems.
 * **AliCloud Object Storage**：massive, secure, low-cost, and highly reliable cloud storage services. Support for storing and accessing any type of data in any application, anytime, anywhere.
 For more features, please refer to [Roadmap](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/Roadmap.md).
 
@@ -23,6 +24,10 @@ For more features, please refer to [Roadmap](https://github.com/spring-cloud-inc
 
 **[Nacos](https://github.com/alibaba/Nacos)**: an easy-to-use dynamic service discovery, configuration and service management platform for building cloud native applications.
 
+**[RocketMQ](https://rocketmq.apache.org/)**：a distributed messaging and streaming platform with low latency, high performance and reliability, trillion-level capacity and flexible scalability.
+
+**[AliCloud ACM](https://www.aliyun.com/product/acm)**：an application configuration center that enables you to centralize the management of application configurations, and accomplish real-time configuration push in a distributed environment.
+
 **[AliCloud OSS](https://www.aliyun.com/product/oss)**: An encrypted and secure cloud storage service which stores, processes and accesses massive amounts of data from anywhere in the world.
 
 For more features please refer to [Roadmap](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/Roadmap.md).
@@ -30,7 +35,7 @@ For more features please refer to [Roadmap](https://github.com/spring-cloud-incu
 ## How to build
 
 * **master branch**: Corresponds to Spring Boot 2.x. JDK 1.8 or later versions are supported.
-* **1.x branch**: Corresponds to Spring Boot 1.x，JDK 1.7 or later versions are supported.
+* **1.x branch**: Corresponds to Spring Boot 1.x, JDK 1.7 or later versions are supported.
 
 Spring Cloud uses Maven for most build-related activities, and you should be able to get off the ground quite quickly by cloning the project you are interested in and typing:
 
@@ -40,7 +45,7 @@ Spring Cloud uses Maven for most build-related activities, and you should be abl
 ## How to Use
 
 ### Add maven dependency
-Version 0.2.0.RELEASE is compatible with the Spring Boot 2.0.x line. Version 0.1.0.RELEASE is compatible with the Spring Boot 1.x line.
+Version 0.2.0.RELEASE is compatible with the Spring Cloud Finchley. Version 0.1.0.RELEASE is compatible with the Spring Cloud Edgware.
 
 These artifacts are available from Maven Central and Spring Release repository via BOM:
 
@@ -95,6 +100,8 @@ Examples：
 
 [Nacos Discovery Example](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/spring-cloud-alibaba-examples/nacos-example/nacos-discovery-example/readme.md)
 
+[RocketMQ Example](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/spring-cloud-alibaba-examples/rocketmq-example/readme.md)
+
 [AliCloud OSS Example](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/blob/master/spring-cloud-alibaba-examples/oss-example/readme.md)
 
 ## Version control guidelines
@@ -104,8 +111,8 @@ As the interfaces and annotations of Spring Boot 1 and Spring Boot 2 have been c
 * 0.1.x for Spring Boot 1
 * 0.2.x for Spring Boot 2
 
-During the incubation period，the version management of the project will follow these rules：
+During the incubation period, the version management of the project will follow these rules：
-* Functional updates will be reflected in the 3rd number of the version, for example, the next version of 0.1.0 will be 0.1.1。
+* Functional updates will be reflected in the 3rd number of the version, for example, the next version of 0.1.0 will be 0.1.1.
 
 
 ## Contact Us

spring-cloud-alibaba-examples/rocketmq-example/readme-zh.md

@@ -75,7 +75,7 @@ spring.cloud.stream.bindings.input.group=test-group
 
 ### 下载并启动 RocketMQ
 
-在接入 RocketMQ Binder 之前，首先需要启动 RocketMQ 的 Name Server 和 Broker。
+**在接入 RocketMQ Binder 之前，首先需要启动 RocketMQ 的 Name Server 和 Broker。**
 
 1. 下载[RocketMQ最新的二进制文件](https://www.apache.org/dyn/closer.cgi?path=rocketmq/4.3.2/rocketmq-all-4.3.2-bin-release.zip)，并解压
 

spring-cloud-alibaba-examples/rocketmq-example/readme.md

@@ -0,0 +1,271 @@
+# RocketMQ Example
+
+## Project Instruction
+
+This example illustrates how to use RocketMQ Binder implement pub/sub messages for Spring Cloud applications.
+
+[RocketMQ](https://rocketmq.apache.org/) is a distributed messaging and streaming platform with low latency, high performance and reliability, trillion-level capacity and flexible scalability.
+
+Before we start the demo, let's look at Spring Cloud Stream.
+
+Spring Cloud Stream is a framework for building message-driven microservice applications. Spring Cloud Stream builds upon Spring Boot to create standalone, production-grade Spring applications and uses Spring Integration to provide connectivity to message brokers. It provides opinionated configuration of middleware from several vendors, introducing the concepts of persistent publish-subscribe semantics, consumer groups, and partitions.
+
+There are two concepts in Spring Cloud Stream: Binder 和 Binding.
+
+* Binder: A strategy interface used to bind an app interface to a logical name.
+
+Binder Implementations includes `KafkaMessageChannelBinder` of kafka, `RabbitMessageChannelBinder` of RabbitMQ and `RocketMQMessageChannelBinder` of `RocketMQ`.  
+
+* Binding: Including Input Binding and Output Binding.
+
+Binding is Bridge between the external messaging systems and application provided Producers and Consumers of messages.
+
+This is a overview of Spring Cloud Stream.
+
+![](https://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/images/SCSt-overview.png)
+
+## Demo
+
+### Integration with RocketMQ Binder
+
+Before we start the demo, let's learn how to Integration with RocketMQ Binder to a Spring Cloud application.
+
+**Note: This section is to show you how to connect to Sentinel. The configurations have been completed in the following example, so you don't need modify the code any more.**
+
+1. Add dependency spring-cloud-starter-stream-rocketmq in the pom.xml file in your Spring Cloud project.
+
+```xml
+<dependency>
+    <groupId>org.springframework.cloud</groupId>
+    <artifactId>spring-cloud-starter-stream-rocketmq</artifactId>
+</dependency>
+```
+
+2. Configure Input and Output Binding and cooperate with `@EnableBinding` annotation
+
+```java
+@SpringBootApplication
+@EnableBinding({ Source.class, Sink.class })
+public class RocketMQApplication {
+	public static void main(String[] args) {
+		SpringApplication.run(RocketMQApplication.class, args);
+	}
+}
+```
+
+Configure Binding:
+```properties
+# configure the nameserver of rocketmq
+spring.cloud.stream.rocketmq.binder.namesrv-addr=127.0.0.1:9876
+# configure the output binding named output
+spring.cloud.stream.bindings.output.destination=test-topic
+spring.cloud.stream.bindings.output.content-type=application/json
+# configure the input binding named input
+spring.cloud.stream.bindings.input.destination=test-topic
+spring.cloud.stream.bindings.input.content-type=application/json
+spring.cloud.stream.bindings.input.group=test-group
+
+```
+	
+3. pub/sub messages
+
+### Download and Startup RocketMQ
+
+You should startup Name Server and Broker before using RocketMQ Binder.
+
+1. Download [RocketMQ](https://www.apache.org/dyn/closer.cgi?path=rocketmq/4.3.2/rocketmq-all-4.3.2-bin-release.zip) and unzip it.
+
+2. Startup Name Server
+
+```bash
+sh bin/mqnamesrv
+```
+
+3. Startup Broker
+
+```bash
+sh bin/mqbroker -n localhost:9876
+```
+
+4. Create topic: test-topic
+
+```bash
+sh bin/mqadmin updateTopic -n localhost:9876 -c DefaultCluster -t test-topic
+```
+
+### Start Application
+
+1. Add necessary configurations to file `/src/main/resources/application.properties`.
+	
+```properties
+spring.application.name=rocketmq-example
+server.port=28081
+```
+	
+2. Start the application in IDE or by building a fatjar.
+
+	1. Start in IDE: Find main class  `RocketMQApplication`, and execute the main method.
+    2. Build a fatjar: Execute command `mvn clean package` to build a fatjar, and run command `java -jar rocketmq-example.jar` to start the application.
+
+
+### Message Handle
+
+Using the binding named output and sent messages to `test-topic` topic.
+
+And using two input bindings to subscribe messages.
+
+* input1: subscribe the message of `test-topic` topic and consume ordered messages(all messages should in the same MessageQueue if you want to consuming ordered messages).
+
+* input2: subscribe the message of `test-topic` topic and consume concurrent messages which tags is `tagStr`, the thread number in pool is 20 in Consumer side.
+
+see the configuration below:
+
+```properties
+spring.cloud.stream.rocketmq.binder.namesrv-addr=127.0.0.1:9876
+
+spring.cloud.stream.bindings.output.destination=test-topic
+spring.cloud.stream.bindings.output.content-type=application/json
+
+spring.cloud.stream.bindings.input1.destination=test-topic
+spring.cloud.stream.bindings.input1.content-type=text/plain
+spring.cloud.stream.bindings.input1.group=test-group1
+spring.cloud.stream.rocketmq.bindings.input1.consumer.orderly=true
+
+spring.cloud.stream.bindings.input2.destination=test-topic
+spring.cloud.stream.bindings.input2.content-type=text/plain
+spring.cloud.stream.bindings.input2.group=test-group2
+spring.cloud.stream.rocketmq.bindings.input2.consumer.orderly=false
+spring.cloud.stream.rocketmq.bindings.input2.consumer.tags=tagStr
+spring.cloud.stream.bindings.input2.consumer.concurrency=20
+
+```
+
+#### Pub Messages
+
+Using MessageChannel to send messages:
+
+```java
+public class ProducerRunner implements CommandLineRunner {
+    @Autowired
+    private MessageChannel output;
+    @Override
+    public void run(String... args) throws Exception {
+        Map<String, Object> headers = new HashMap<>();
+        headers.put(MessageConst.PROPERTY_TAGS, "tagStr");
+        Message message = MessageBuilder.createMessage(msg, new MessageHeaders(headers));
+        output.send(message);
+    }
+}
+```
+
+Or you can using the native API of RocketMQ to send messages:
+
+```java
+public class RocketMQProducer {
+    DefaultMQProducer producer = new DefaultMQProducer("producer_group");
+    producer.setNamesrvAddr("127.0.0.1:9876");
+    producer.start();
+    
+    Message msg = new Message("test-topic", "tagStr", "message from rocketmq producer".getBytes());
+    producer.send(msg);
+}
+```
+
+#### Sub Messages
+
+Using `@StreamListener` to receive messages:
+
+```java
+@Service
+public class ReceiveService {
+
+	@StreamListener("input1")
+	public void receiveInput1(String receiveMsg) {
+		System.out.println("input1 receive: " + receiveMsg);
+	}
+
+	@StreamListener("input2")
+	public void receiveInput2(String receiveMsg) {
+		System.out.println("input2 receive: " + receiveMsg);
+	}
+
+}
+```
+
+## Endpoint
+
+Add dependency `spring-cloud-starter-stream-rocketmq` to your pom.xml file, and configure your endpoint security strategy.
+
+* Spring Boot1.x: Add configuration `management.security.enabled=false`    
+* Spring Boot2.x: Add configuration `management.endpoints.web.exposure.include=*`
+
+To view the endpoint information, visit the following URLS:
+* Spring Boot1.x: Sentinel Endpoint URL is http://127.0.0.1:18083/rocketmq_binder.
+* Spring Boot2.x: Sentinel Endpoint URL is http://127.0.0.1:18083/actuator/rocketmq-binder.
+
+Endpoint will metrics some data like last send timestamp, sending or receive message successfully times or unsuccessfully times. 
+
+```json
+{
+	"runtime": {
+		"lastSend.timestamp": 1542786623915
+	},
+	"metrics": {
+		"scs-rocketmq.consumer.test-topic.totalConsumed": {
+			"count": 11
+		},
+		"scs-rocketmq.consumer.test-topic.totalConsumedFailures": {
+			"count": 0
+		},
+		"scs-rocketmq.producer.test-topic.totalSentFailures": {
+			"count": 0
+		},
+		"scs-rocketmq.consumer.test-topic.consumedPerSecond": {
+			"count": 11,
+			"fifteenMinuteRate": 0.012163847780107841,
+			"fiveMinuteRate": 0.03614605351360527,
+			"meanRate": 0.3493213353657594,
+			"oneMinuteRate": 0.17099243039490175
+		},
+		"scs-rocketmq.producer.test-topic.totalSent": {
+			"count": 5
+		},
+		"scs-rocketmq.producer.test-topic.sentPerSecond": {
+			"count": 5,
+			"fifteenMinuteRate": 0.005540151995103271,
+			"fiveMinuteRate": 0.01652854617838251,
+			"meanRate": 0.10697493212602836,
+			"oneMinuteRate": 0.07995558537067671
+		},
+		"scs-rocketmq.producer.test-topic.sentFailuresPerSecond": {
+			"count": 0,
+			"fifteenMinuteRate": 0.0,
+			"fiveMinuteRate": 0.0,
+			"meanRate": 0.0,
+			"oneMinuteRate": 0.0
+		},
+		"scs-rocketmq.consumer.test-topic.consumedFailuresPerSecond": {
+			"count": 0,
+			"fifteenMinuteRate": 0.0,
+			"fiveMinuteRate": 0.0,
+			"meanRate": 0.0,
+			"oneMinuteRate": 0.0
+		}
+	}
+}
+```
+
+Note: You should add [metrics-core dependency](https://mvnrepository.com/artifact/io.dropwizard.metrics/metrics-core) if you want to see metrics data. endpoint will show warning information if you don't add that dependency:
+
+```json
+{
+    "warning": "please add metrics-core dependency, we use it for metrics"
+}
+```
+
+## More
+
+For more information about RocketMQ, see [RocketMQ Project](https://rocketmq.apache.org).
+
+If you have any ideas or suggestions for Spring Cloud RocketMQ Binder, please don't hesitate to tell us by submitting github issues.
+