Polish the documents of building consumers
diff --git a/java-chassis-reference/en_US/build-consumer/develop-consumer-using-rpc.md b/java-chassis-reference/en_US/build-consumer/develop-consumer-using-rpc.md
index 941eacf..e1871d8 100644
--- a/java-chassis-reference/en_US/build-consumer/develop-consumer-using-rpc.md
+++ b/java-chassis-reference/en_US/build-consumer/develop-consumer-using-rpc.md
@@ -1,79 +1,56 @@
-# Develop with RPC
-## Concept Description
+# Develop consumer with transparent RPC
+## Concepts
-The RPC development mode allows you to add annotations on the microservice APIs to generate the service provider agent. In this case, you can call microservices.
+The transparent RPC allows user to access services like a local call through a simple java interface.
+Transparent RPC is just a development mode:
-## Sample Code
+- Not associated with highway or RESTful transport
+- The RPC does not rely on producers' development mode(transparent RPC/Jax-RS or SpringMVC)
+- The RPC works even if the producer doesn't implement the interface.
-To call a microservice, you only need to declare a member of a service API type and add the @RpcReference annotation for the member, the microservice that depends on the declaration, and the schemaID. The sample code is as follows.
+The transparent RPC is similar to spring cloud's feign, but simpler because there is no need to add any RESTful annotations in interface.
+
+
+
+## Declare PRC by @RpcReference in spring bean
```java
-import org.springframework.stereotype.Component;
-
-import org.apache.servicecomb.foundation.common.utils.BeanUtils;
-import org.apache.servicecomb.foundation.common.utils.Log4jUtils;
-import org.apache.servicecomb.provider.pojo.RpcReference;
-import org.apache.servicecomb.samples.common.schema.Hello;
-import org.apache.servicecomb.samples.common.schema.models.Person;
-
@Component
-public class CodeFirstConsumerMain {
- @RpcReference(microserviceName = "codefirst", schemaId = "codeFirstHello")
- private static Hello hello;
-
- public static void main(String[] args) throws Exception {
- init();
- System.out.println(hello.sayHi("Java Chassis"));
- Person person = new Person();
- person.setName("ServiceComb/Java Chassis");
- System.out.println(hello.sayHello(person));
- }
-
- public static void init() throws Exception {
- Log4jUtils.init();
- BeanUtils.init();
- }
+public class SomeBean {
+ ......
+
+ @RpcReference(microserviceName = "helloService", schemaId = "helloSchema")
+ private Hello hello;
+
+ ......
}
```
-In the preceding code, the microservice consumers have obtained the microservice API Hello of the microservice provider and declared a member of the Hello type. The annotation `@RPCReference` on `Hello` specifies the microservice name and schemaId, The ServiceComb framework can obtain information about isntances from a certain provider during program startup and generate an agent to insert to Hello. This allows you to call a remote service in the same way as you call a local class.
-
-### Additional explanation for consumer invocation
-In above example, in order to direct use `hello` in main function, we mark it as `static`. As a local field of `CodeFirstConsumerMain`, we recommend get it use these two way :
-
-#### First way: define cse:rpc-reference
-In your bean.xml, add `cse:rpc-reference` configuration:
-
-```xml
-<cse:rpc-reference id="hello" microservice-name="codefirst"
- schema-id="codeFirstHello" interface="org.apache.servicecomb.samples.common.schema.Hello"></cse:rpc-reference>
-```
-
-Then use `BeanUtils.getBean` to get `Hello` provider:
+## Declare by API without spring bean
```java
-Hello hello = BeanUtils.getBean("hello");
+Hello hello = Invoker.createProxy("helloService", "helloSchema", Hello.class);
```
-#### Second way: get Bean, then use field
-First use `BeanUtils.getBean` to get Bean of `CodeFirstConsumerMain`:
+## reactive
+
+Just use jdk's CompletableFuture to wrap the return value:
```java
-//Default instance name of Spring Bean is same as class name with first char low-cased
-CodeFirstConsumerMain consumer = BeanUtils.getBean("codeFirstConsumerMain");
-```
-
-Then get `hello` via Getter：
-
-```java
-public Hello getHello() {
- return hello;
+interface Hello {
+ CompletableFuture<String> sayHi(String name);
}
```
+In the same interface, you can declare both the reactive and synchronous prototypes of the same method.
+It is illegal in java that the method name is the same with the operationId in the contract while the return value type is different, so you need to modify the method name and declare the real operationId through the swagger annotation.
+
```java
-Hello hello = consumer.getHello()
+interface Hello {
+ String sayHi(String name);
+
+ @ApiOperation(nickname = "sayHi", value = "reactive method for sayHi")
+ CompletableFuture<String> asyncSayHi(String name);
+}
```
-> NOTE:
-> `BeanUtils.getBean` has inner lock so performacen is low , we recommend use once and cache return as local field for future use(such as in constructor).
\ No newline at end of file
diff --git a/java-chassis-reference/en_US/build-consumer/using-AsyncRestTemplate.md b/java-chassis-reference/en_US/build-consumer/using-AsyncRestTemplate.md
index 2152d81..3f42da5 100644
--- a/java-chassis-reference/en_US/build-consumer/using-AsyncRestTemplate.md
+++ b/java-chassis-reference/en_US/build-consumer/using-AsyncRestTemplate.md
@@ -1,14 +1,14 @@
-# 使用AsynRestTemplate开发服务消费者
+# Develop consumer with AsynRestTemplate
-## 概念阐述
+## Concepts
-AsyncRestTemplate 开发方式允许用户异步的进行服务调用。具体的业务流程和 restTemplate 类似，只是这里以异步的形式进行服务的调用。
+AsyncRestTemplate allows users to make asynchronous service calls. The logic is similar to restTemplate, except that the service is called asynchronously.
-## 示例代码
+## Sample code
-AsyncRestTemplate 实例通过 new CseAsyncRestTemplate（）来创建和获取，再使用该实例通过自定义的 URL 进行服务调用。
+The AsyncRestTemplate instance is created and retrieved via `new CseAsyncRestTemplate()`, which is then used to make service calls through a custom URL.
-* Spring MVC 客户端代码示例
+* Spring MVC client sample code
```java
@@ -32,7 +32,7 @@
.exchange("cse://springmvc/springmvchello/sayhello", HttpMethod.POST, entity, String.class);
// ResponseEntity<String> responseEntity1 = listenableFuture.get();
// System.out.println("AsyncRestTemplate Consumer sayHello services: " + responseEntity1.getBody());
- //设置回调函数
+ // Set the callback function
listenableFuture.addCallback(
new ListenableFutureCallback<ResponseEntity<String>>() {
@Override
@@ -55,7 +55,8 @@
```
-> 说明 ：
+> Note
>
-> * URL 的格式和 RestTemplate 一样，具体可以参考 restTemplate
-> * 这里用自定义的 ListenableFuture 类来作为占位符，获取远程调用结束后可能获取的结果。同时也可以自定义回调函数，对可能返回的结果进行分批处理。
+> * The URL format is the same with RestTemplate, refer to restTemplate for details
+> * The custom ListenableFuture class is the placeholder to get the results from the remote call. Users can also customize the callback function to process the return results in batches.
+
diff --git a/java-chassis-reference/en_US/build-consumer/using-resttemplate.md b/java-chassis-reference/en_US/build-consumer/using-resttemplate.md
index 879ec94..4a2e34a 100644
--- a/java-chassis-reference/en_US/build-consumer/using-resttemplate.md
+++ b/java-chassis-reference/en_US/build-consumer/using-resttemplate.md
@@ -1,15 +1,19 @@
-# Develop with Rest Template
-## Concept Description
+# Develop consumer with Rest Template
+## Concepts
- Rest Template is a RESTful API provide by the Spring framework. ServiceComb provides the API for service calling
+Rest Template is a RESTful API provided by the Spring framework. ServiceComb provides the implementation class for service calling
## Scenario
- You can call microservices using your customized URL and the RestTemplate instance provided by ServiceComb regardless of the specific address of the service.
+With ServiceComb's RestTemplate instance, users can call the service with a customized URL without knowing the service's address.
+
+
## Sample Code
- Obtain RestTemplate by calling `RestTemplateBuilder.create()`. Then, use the instance and the customized URL to call microservices. The code is as follows:
+The RestTemplate instance is created by the static method `RestTemplateBuilder.create()`. Then, users can call the microservices with the instance and the customized URL. The code is as follows:
+
+- Sample code for Sprint MVC consumer
```java
import org.springframework.stereotype.Component;
@@ -43,10 +47,33 @@
}
```
+- Sample code for JAX RS Consumer:
+
+```java
+@Component
+public class JaxrsConsumerMain {
+
+ public static void main(String[] args) throws Exception {
+ init();
+ // The rest is just like the Spring MVC Consumer sample code, notice that if the provider only accepts GET requests, the consumer should use method getForObject()
+ RestTemplate restTemplate = RestTemplateBuilder.create();
+ String result = restTemplate.getForObject("cse://jaxrs/jaxrshello/saybye", String.class);
+ }
+
+ public static void init() throws Exception {
+ Log4jUtils.init();
+ BeanUtils.init();
+ }
+}
+```
+> NOTE:
+>
+> - The URL should be in format: `cse//microserviceName/path?querystring`. Taking the provider example from [Develop micro service with SpringMVC](/java-chassis-reference/en_US/build-provider/springmvc.md), the micro service's name is `springmvc`, the basePath is `/springmvchello`, then the microserviceName in the URL is `springmvc`, the path to call sayhi is `springmvchello/sayhi`, so the URL for sayhi in the sample is `cse://springmvc/springmvchello/sayhi?name=Java Chassis`, below is the code for the provider:
+
```java
@RestSchema(schemaId = "springmvcHello")
@RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
-//Here, springmvchello in path = "/springmvchello" is the above basePath.
+//这里 path = “/springmvchello” 中的 springmvchello 就是 上述的basePath
public class SpringmvcHelloImpl implements Hello {
@Override
@RequestMapping(path = "/sayhi", method = RequestMethod.POST)
@@ -61,12 +88,15 @@
}
}
```
-> The following code is microservice.yaml in the resources directory of the springmvc-provider module of the sample project [Spring MVC] (https://github.com/apache/incubator-service comb-java-chassis/tree/master/samples/springmvc-sample)
+
+
+
+> The following configuration is the file `resources/microservice.yaml` of the springmvc-provider module in the [SpringMVC sample](https://github.com/apache/incubator-servicecomb-java-chassis/tree/master/samples/springmvc-sample):
```yaml
APPLICATION_ID: springmvc-sample
service_description:
- name: springmvc # 这里就是定义的微服务名称
+ name: springmvc # The name of the micro service
version: 0.0.2
servicecomb:
service:
@@ -86,6 +116,4 @@
address: http://127.0.0.1:30100 #service center address
```
-> NOTE:
-- The URL must be in format of ServiceComb: `cse://microserviceName/path?querystring`. Use the provider defined in [Develop Microservice with SpringMVC](/users/develop-with-springmvc/) as an example. The microservice name is `springmvc`, and its base path is `/springmvchello`, so you should set microserviceName in the URL to `springmvchello/sayhi` when requesting sayhi. Therefore, the URL for requesting sayhi is `cse://springmvc/springmvchello/sayhi?name=Java Chassis`.
-- During use of this URL format, the ServiceComb framework will perform internal microservice descovery, fallbreak, and fault tolerance and send the requests to the microservice providers.
+- With the URL format, ServiceComb framework will perform internal microservice descovery, fallback, fault tolerance and send the requests to the microservice providers.
diff --git a/java-chassis-reference/en_US/build-consumer/with-contract.md b/java-chassis-reference/en_US/build-consumer/with-contract.md
index 8e72c10..54d077a 100644
--- a/java-chassis-reference/en_US/build-consumer/with-contract.md
+++ b/java-chassis-reference/en_US/build-consumer/with-contract.md
@@ -1,11 +1,15 @@
-# Service Using API Definitions
+# Using Contracts
## Scenario
-When a consumer calls a service from a provider, you need to register a service API definition. You can obtain service API definition from your provider for your consumer in two ways. One is to obtain the service API definition from the provider off-line and manually configure the API definition to the project. Another is to automatically download the service API definition from the service center.
+When a consumer calls a service from a provider, the contract is required. The consumer can get the providers' contracts in 2 ways: get the providers' contract from off-line, then manually configure it in the project. Or, download the contract from the service center.
## Configuration
-> You can obtain service API definition in either way, regardless of the development mode of service consumers.
+> NOTE
+>
+> Users can get the contract in either way, regardless of the consumers' development mode.
+
+## Configure the Dependencies
In the microservice.yaml file, configure a provider for the consumer. The following is an example of the configuration:
@@ -17,31 +21,32 @@
version-rule: 0.0.1
```
-> There are four kind of rule for version-rule:
+> The version-rule field is the rules to match the version, there are 4 version-rule formats:
>
-> * Accurate Matching Rule: such as `version-rule: 0.0.1`, it indicates that only those providers whose version is 0.0.1 can be matched.
-> * Later Matching Rule: such as `version-rule: 1.0.0+`, it indicates that those providers whose version is later that 1.0.0 can be matched.
-> * Latest Matching Rule: such as `version-rule: latest`, it indicates that only those providers whose version number is latest can be matched.
-> * Range Matching Rule: such as`1.0.0-2.0.2`, it indicates that those provider whose version number is between 1.0.0 and 2.0.2 can be matched, including 1.0.0 and 2.0.2
+> * Accurate version: such as `version-rule: 0.0.1`, it indicates that only those providers with version 0.0.1 are matched.
+> * Later versions: such as `version-rule: 1.0.0+`, it indicates that those providers with version greater than 1.0.0 are matched.
+> * Latest version: `version-rule: latest`, it indicates that only those providers with the latest are matched.
+> * Version range: such as`1.0.0-2.0.2`, it indicates that those provider with versions between 1.0.0 and 2.0.2 are matched, including 1.0.0 and 2.0.2
>
-> The default version rule of version-rule is `latest`.
+> The default version matching rule is `latest`.
-### Manually Configuring Service API Definition
+### Manually Configure Contracts
-After you obtained the API definition of your consumer from the provider, configure it in a specified directory of the consumer project. The directory is the one mentioned in the configuration description [Service Contract](/users/service-contract/).
+When providers' contracts are obtained from off-line, they should be put into the specific directory of the consumer project. The directory is the one mentioned in the configuration description [Service Contract](/java-chassis-reference/en_US/build-provider/define-contract.md).
-Each directory under the microservices directory indecates a microservice, and each .yaml file under the jaxrs directory represents a schema API definition. The file name is the schema ID. The service API definitions whose application IDs need to be specified are stored under the applications directory for cross-application calls. The directory structure is as follows:
+Each directory under the microservices directory indicates a microservice, and each yaml file under the microservice directory represents a contract schema. The file name is the schemaId. The contracts stored in application folder should specify the appId for cross application access. The directory tree is as follows:
+
```txt
resources
- microservices
- serviceName # Microservice name
- - schemaId.yaml # Schema API definition
+ - schemaId.yaml # The contract schemaId
- applications
- appId # Application ID
- serviceName # Microservice name
- - schemaId.yaml # Schema API definition
+ - schemaId.yaml # The contract schemaId
```
-### Automatically Downloading API Definition from Service Center
+### Automatically Download Contract from Service Center
-If a consumer does not explicitly store the API definition in the project directory, when the application is started, the ServiceComb framework automatically downloads the information about the API definition from the service center based on the provider's microservices name and version configured in microservice.yaml.
+If a consumer does not explicitly store the contract in the project, when the application starts, ServiceComb framework automatically downloads contracts from the service center based on the providers' microservices name and version configured in microservice.yaml.
diff --git a/java-chassis-reference/en_US/catalog/build-consumer.md b/java-chassis-reference/en_US/catalog/build-consumer.md
index 15b0916..734c806 100644
--- a/java-chassis-reference/en_US/catalog/build-consumer.md
+++ b/java-chassis-reference/en_US/catalog/build-consumer.md
@@ -1,26 +1,26 @@
-## Using RestTemplate to develop service consumers
-RestTemplate is a RESTful access interface provided by Spring. ServiceComb provides an implementation class for this interface for service calls.
+## Develop consumer with Rest Template
+Rest Template is a RESTful API provided by the Spring framework. ServiceComb provides the implementation class for service calling
-## Using AsynRestTemplate to develop service consumers
-The AsyncRestTemplate development method allows users to make service calls asynchronously. The specific business process is similar to restTemplate, except that the service is called asynchronously.
+## Develop consumer with AsynRestTemplate
+AsyncRestTemplate allows users to make asynchronous service calls. The logic is similar to restTemplate, except that the service is called asynchronously.
-## Using a transparent RPC approach to develop service consumers
+## Develop consumer with transparent RPC
-The transparent RPC development model allows users to make service calls like a local call through a simple java interface.
+The transparent RPC allows users to make service calls like a local call through a simple java interface.
-## Using a service contract
-When a service consumer invokes a service provider's service, a service contract needs to be registered. Consumers have two ways to obtain the provider's service contract. One is to obtain the contract file offline from the provider of the service and manually configure it into the project; the other is to automatically download the contract from the service center.
+## Using Contracts
+When a consumer calls a service from a provider, the contract is required. The consumer can get the providers' contracts in 2 ways: get the providers' contract from off-line, then manually configure it in the project. Or, download the contract from the service center.
## Call Control
### Instance level fault isolation
-The instance-level fault isolation feature allows the ability to isolate a failed instance by stopping the sending of a request to the failed instance when a partial instance call to the microservice fails.
+The instance-level fault isolation feature introduces the ability to isolate failed service instances by stopping sending request to them.
-### Fuse strategy
-The fuse strategy is the setting of the ServiceComb fuse function. The user can specify the conditions under which the ServiceComb framework will terminate the send request by configuring the fuse policy.
+### Fallback strategy
+The fallback strategy allows user to specify the conditions under which the ServiceComb framework will terminate the requests.
-### Current limiting strategy
-The user uses the traffic limiting policy on the consumer side to limit the frequency of requests sent to the specified microservice.
+### Rate limiting strategy
+The user uses the rate limiting policy on the consumer side to control the frequency of requests sent to the specified microservice.
### Fault injection
-The user uses fault injection on the consumer side to set the delay and error of the request to the specified microservice and its trigger probability.
\ No newline at end of file
+The user uses fault injection on the consumer side to set the delay and error of the request sent to the specified microservice and its trigger probability.
\ No newline at end of file
diff --git a/java-chassis-reference/zh_CN/build-consumer/using-resttemplate.md b/java-chassis-reference/zh_CN/build-consumer/using-resttemplate.md
index 8f4528b..f9eb693 100644
--- a/java-chassis-reference/zh_CN/build-consumer/using-resttemplate.md
+++ b/java-chassis-reference/zh_CN/build-consumer/using-resttemplate.md
@@ -61,7 +61,7 @@
> 说明：
>
-> * URL格式为：`cse://microserviceName/path?querystring`。以[用SpringMVC开发微服务](/用SpringMVC开发微服务)中定义的服务提供者为例，其微服务名称是springmvc，basePath是`/springmvchello`，那么URL中的microserviceName=`springmvc`，请求sayhi时的path=`springmvchello/sayhi`，所以示例代码中请求sayhi的URL是`cse://springmvc/springmvchello/sayhi?name=Java Chassis`。具体代码示例如下 ：
+> * URL格式为：`cse://microserviceName/path?querystring`。以[用SpringMVC开发微服务](/用SpringMVC开发微服务)中定义的服务提供者为例，其微服务名称是`springmvc`，basePath是`/springmvchello`，那么URL中的microserviceName=`springmvc`，请求sayhi时的path=`springmvchello/sayhi`，所以示例代码中请求sayhi的URL是`cse://springmvc/springmvchello/sayhi?name=Java Chassis`。具体代码示例如下 ：
```java
