Polish the documents of protocols.
diff --git a/java-chassis-reference/en_US/build-provider/protocol.md b/java-chassis-reference/en_US/build-provider/protocol.md
index fddcd8b..fca2c74 100644
--- a/java-chassis-reference/en_US/build-provider/protocol.md
+++ b/java-chassis-reference/en_US/build-provider/protocol.md
@@ -1,7 +1,7 @@
# Communication Protocol
-### Concept Description
+### Concepts
-ServiceComb uses two network channels, REST and Highway, both supporting encrypted Transport Layer Security (TLS) transmission. The REST channel releases services in the standard RESTful form. The consumer can send requests using http client.
+ServiceComb uses two network channels, REST and Highway, both support encrypted Transport Layer Security (TLS) transmission. The REST channel provides services in the standard RESTful form. The consumer can call RESTful APIs with http client.
### Precautions
diff --git a/java-chassis-reference/en_US/build-provider/protocol/highway-rpc.md b/java-chassis-reference/en_US/build-provider/protocol/highway-rpc.md
index ee003d2..a9b0ee2 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/highway-rpc.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/highway-rpc.md
@@ -1,11 +1,11 @@
## Highway RPC Protocol
### Concept Description
-Highway is a high-performance proprietary protocol of ServiceComb, and you can use it in scenarios having special performance requirements.
+Highway is ServiceComb's private high-performance protocol, it's suitable for the performance sensitive scenarios.
### Configuration
-To use the Highway communication channel, you need to add the following dependencies in the maven pom.xml file:
+To use the Highway channel, add the following dependencies in the pom.xml file:
```xml
<dependency>
@@ -14,23 +14,23 @@
</dependency>
```
-Configuration items that need to be set in the microservice.yaml file are described as follows:
+The Highway configuration items in the microservice.yaml file are described below:
-Table 3 Configuration items of Highway
+Table 1-1 Highway configuration items
-| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
-| :--------------------------------------- | :------------ | :---------- | :-------- | :--------------------------------------- | :--------------------------------------- |
-| servicecomb.highway.address | 0.0.0.0:7070 | - | No | Specifies the server listening IP address. | - |
-| servicecomb.highway.server.thread-count | 1 | - | No | Specifies the number of server network threads. | - |
-| servicecomb.highway.client.thread-count | 1 | - | No | Specifies the number of client network threads. | - |
-| servicecomb.highway.client.connection-pool-per-thread | 1 | - | No | Specifies the number of connection pools in each client thread. | - |
-| servicecomb.request.timeout | 30000 | - | No | Specifies the request timeout duration. | The configuration of this parameter for Highway is the same as that for REST over Vertx. |
-| servicecomb.references.\[服务名\].transport | rest | | No | Specifies the accessed transport type. | The configuration of this parameter for Highway is the same as that for REST over Vertx. |
-| servicecomb.references.\[服务名\].version-rule | latest | - | No | Specifies the version of the accessed instance. | The configuration of this parameter for Highway is the same as that for REST over Vertx. |
+| Configuration Item | Default Value | Value Range | Required | Description | Remark |
+| :---------------------------------------------------- | :------------ | :---------- | :------- | :------------------------------------------- | :--------------------------------------------------- |
+| servicecomb.highway.address | 0.0.0.0:7070 | - | No | The address that the server listens | - |
+| servicecomb.highway.server.thread-count | 1 | - | No | The number of server network threads | - |
+| servicecomb.highway.client.thread-count | 1 | - | No | The max number of allowed client connections | - |
+| servicecomb.highway.client.connection-pool-per-thread | 1 | - | No | The number of client network threads | - |
+| servicecomb.request.timeout | 30000 | - | No | The request timeout duration | The same with the configuration of "REST over Vertx" |
+| servicecomb.references.\[servicename\].transport | rest | | No | The transport type of the request | The same with the configuration of "REST over Vertx" |
+| servicecomb.references.\[servicename\].version-rule | latest | - | No | The version of the requested instance. | The same with the configuration of "REST over Vertx" |
-###
+### Sample code
-An example of the configuration in the microservice.yaml file for Highway is as follows:
+An example of the Highway configuration in the microservice.yaml:
```yaml
servicecomb:
diff --git a/java-chassis-reference/en_US/build-provider/protocol/http2.md b/java-chassis-reference/en_US/build-provider/protocol/http2.md
index 9b2d542..fd1ebfe 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/http2.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/http2.md
@@ -1,13 +1,14 @@
-## Scene Description
+## Scenario
-Users can enable Http2 to communicate and improve performance through simple configuration.
+Users can easily enable Http2 protocol for better performance through configuration.
## External Service Communication Configuration
-The configuration related to external service communication is written in the microservice.yaml file.
+The configuration for external service communication is in the microservice.yaml file.
-* Enable h2\(Http2 + TLS\) for communication
- When configuring the service listening address, the server can enable TLS communication by appending `?sslEnabled=true` to the address. For details, see the section [Using TLS Communication] (../../security/tls.md). Then add `&protocol=http2` to enable h2 communication. An example is as follows:
+* Enable h2\(Http2 + TLS\)
+
+ Append `?sslEnabled=true` to the listening address to enable TLS communication on server side. For details, see the section [Using TLS Communication](../../security/tls.md). Then add `&protocol=http2` to enable h2 communication. Here is the sample configuration:
```yaml
servicecomb:
@@ -17,8 +18,9 @@
address: 0.0.0.0:7070?sslEnabled=true&protocol=http2
```
-* Enable h2c\(Http2 without TLS\) for communication
- When the server configures the service listening address, the server can enable h2c communication by appending `?protocol=http2` to the address. An example is as follows:
+* Enable h2c\(Http2 without TLS\)
+
+ Simply add `?protocol=http2` to enable h2c communication in the server's configuration:
```yaml
servicecomb:
@@ -27,7 +29,4 @@
highway:
address: 0.0.0.0:7070?protocol=http2
```
-* The client will communicate using http2 by reading the configuration in the server address from the service center.
-
-
-
+* The client will read the server's address configuration from service center, then communicate with the server by http2 protocol.
diff --git a/java-chassis-reference/en_US/build-provider/protocol/rest-over-servlet.md b/java-chassis-reference/en_US/build-provider/protocol/rest-over-servlet.md
index e4ddb09..edfd14b 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/rest-over-servlet.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/rest-over-servlet.md
@@ -1,9 +1,44 @@
-## REST over Servlet
-## 配置说明
-与servlet机制配合，涉及到以下几个概念：
-* 启动spring context
- 注意以下几种启动方式，是N选1的关系，不要同时使用。
- * 不使用springMVC的UI或RestController
+# REST over Servlet
+
+The REST over Servlet mode applications runs in web container. You need to create a new servlet project to wrap the microservices, pack them into war packages, and load them into the web container to run.
+
+## Path for external access
+
+Not like running as a standalone process, when the microservice runs in the web container, the web root and servlet url pattern will be different.
+
+For the traditional development framework, the consumer needs to perceive the complete url of the service; for example, the web root is /mywebapp, the url pattern is /rest, and the business-level path is /application, then consumer must access the service via the url /mywebapp/rest/application.
+
+So when the deployment pattern changes, like from web container to a standalone process, the consumer or producer have to modify the code to adapt to the changes.
+
+It is recommended to use ServiceComb's deployment decoupling feature. Whether it is a consumer or a producer, the application don't perceive the web root and url pattern in the code, while ServiceComb will automatically adapt them for the producer instance at runtime.
+
+For some legacy systems, if users expect to use restTemplate.getForObject("cse://serviceName/mywebapp/rest/application"...) without too many changes, then the path of the interface should be defined as /mywebapp/rest/application:
+
+```
+@RestSchema(schemaId = "test")
+@RequestMapping(path = "/mywebapp/rest/application")
+```
+
+However, it is still recommended to use a deployment-independent way to write the code, which introduces less code modifications when the deployment pattern changes.
+
+## maven dependencies
+
+```xml
+<dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-rest-servlet</artifactId>
+</dependency>
+```
+
+## Configurations
+
+When integrating with servlet, there are a few concepts involved:
+
+- Start spring context
+ Note the following startup methods cannot be used at the same time, just choose one of them.
+
+ - Without SpringMVC UI or RestController
+
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
@@ -17,10 +52,13 @@
</listener>
</web-app>
```
- 其中classpath*:META-INF/spring/*.bean.xml，无论任何情况，都可以不在contextConfigLocation中配置，因为ServiceComb机制会确保加载路径中包含它。
- 这里仅仅是个示例，表示如果使用者需要定制contextConfigLocation，可以使用这个方法。
-
- * 使用springMVC的UI或RestController，且存在org.apache.servicecomb.transport.rest.servlet.CseDispatcherServlet
+
+ The classpath*:META-INF/spring/*.bean.xml configured in contextConfigLocation is optional, because the ServiceComb will ensure that it is included in the load path.
+
+ This is just an example to indicate that the user can customize the contextConfigLocation.
+
+ - Use SpringMVC UI or RestController, and org.apache.servicecomb.transport.rest.servlet.CseDispatcherServlet exists
+
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
@@ -36,10 +74,14 @@
</servlet-mapping>
</web-app>
```
- **注意：**
- 该servlet不是ServiceComb的处理入口，仅仅是UI或RestController的处理入口
- * 使用springMVC的UI或RestController，且不存在org.apache.servicecomb.transport.rest.servlet.CseDispatcherServlet
- 需要继承springMVC的DispatcherServlet，再按CseDispatcherServlet的方式，配置自己的实现类
+
+ **Note**
+ This servlet is not the processing entry of ServiceComb, but the processing entry of UI or RestController.
+
+ - Use SpringMVC's UI or RestController, and there is no org.apache.servicecomb.transport.rest.servlet.CseDispatcherServlet
+
+ In this case, the application class should inherit SpringMVC's DispatcherServlet, and then configure its implementation classes in CseDispatcherServlet's way.
+
```
@Override
protected WebApplicationContext createWebApplicationContext(ApplicationContext parent){
@@ -47,11 +89,17 @@
return super.createWebApplicationContext(parent);
}
```
-* ServiceComb servlet
- url pattern根据业务自身规划设置即可，下面的/rest/*仅仅是示例，不是固定值。
- url pattern必须以/\*结尾
- 以下两种声明方式也是多选一的关系，不要同时使用
- * 标准声明
+
+- ServiceComb servlet
+
+ The url pattern can be set according to the business logic. The following /rest/* is just an example, not a fixed value.
+
+ Url pattern must end with /*
+
+ The following two declarations types can not be used at the same time.
+
+ - Standard declaration
+
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
@@ -68,15 +116,21 @@
</servlet-mapping>
</web-app>
```
- * 快捷声明
- 在microservice.yaml文件中指定urlPattern，ServiceComb启动时会自动创建RestServlet，并设置相应的urlPattern：
+
+ - Quick declaration
+
```yaml
servicecomb.rest.servlet.urlPattern: /rest/*
```
-
-## 典型场景配置示例
-* 纯ServiceComb，标准声明
- web.xml
+
+ Specify urlPattern in the microservice.yaml file. When ServiceComb starts, it will automatically create RestServlet and set the corresponding urlPattern.
+
+## Configuration example for typical scenarios
+
+- Standard declaration in pure ServiceComb mode
+
+ web.xml:
+
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
@@ -96,8 +150,10 @@
</servlet-mapping>
</web-app>
```
-* 纯ServiceComb，快捷声明
+
+- Quick declaration in pure ServiceComb mode
web.xml：
+
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
@@ -107,12 +163,17 @@
</listener>
</web-app>
```
+
microservice.yaml：
+
```yaml
servicecomb.rest.servlet.urlPattern: /rest/*
```
-* springMVC UI或RestController接入请求，通过ServiceComb作为consumer发送到内部微服务
- web.xml：
+
+- SpringMVC or RestController provide web services, ServiceComb proxy the requests as consumer
+
+ web.xml：
+
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
@@ -128,10 +189,13 @@
</servlet-mapping>
</web-app>
```
- microservice.yaml：
- 不配置servicecomb.rest.address以及servicecomb.rest.servlet.urlPattern
-* springMVC UI或RestController接入一些请求，同时通过ServiceComb接入另一些请求
- web.xml：
+
+ microservice.yaml：
+ Servicecomb.rest.address and servicecomb.rest.servlet.urlPattern are not configured
+
+- SpringMVC UI/RestController and ServiceComb provide services at the same time
+ web.xml：
+
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
@@ -147,16 +211,21 @@
</servlet-mapping>
</web-app>
```
+
microservice.yaml：
+
```yaml
servicecomb:
rest:
servlet:
urlPattern: /rest/*
address: 0.0.0.0:8080
- ```
-## 使用servlet filter注意事项
-RestServlet工作于异步模式，根据servlet 3.0的标准，整条工作链都必须是异步模式，所以，如果业务在这个流程上增加了servlet filter，也必须将它配置为异步：
+ ```
+
+## Things to notice with servlet filter
+
+RestServlet works in asynchronous mode. According to the servlet 3.0 standard, the entire work chain must be asynchronous. Therefore, the servlet filter should be set to be asynchronous when it's added to the chain:
+
```xml
<filter>
......
@@ -164,3 +233,15 @@
</filter>
```
+## Configuration items
+
+The related items for REST over Servlet in the microservice.yaml are described below:
+
+Table1-1 REST over Servlet Configuration Items
+
+| Configuration Item |Default Value |Range|Required|Description|Remarks |
+| :---------------------------------- | :----------- | :------- | :------- | :---------------------------------- | :----------------------------------------------------------- |
+| servicecomb.rest.address | 0.0.0.0:8080 | - | No |They service listening address| Should be the same with the web container's listening address|
+| servicecomb.rest.server.timeout | 3000 | - | No | Server timeout | In milliseconds |
+| servicecomb.rest.servlet.urlPattern | | | No | Used to simplify servlet+servlet mapping config | This item is used only when servlet+servlet mapping is not configured in web.xml.The format is:/\* or /path/\*, where path can be nested |
+
diff --git a/java-chassis-reference/en_US/build-provider/protocol/rest-over-vertx.md b/java-chassis-reference/en_US/build-provider/protocol/rest-over-vertx.md
index 1512754..734b77f 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/rest-over-vertx.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/rest-over-vertx.md
@@ -1,7 +1,7 @@
## REST over Vertx
### Configuration
-The REST over Vertx communication channel uses the standalone running mode that can be started using the main function. In the main function, you need to initialize logs and load service configuration. The code is as follow:
+The REST over Vertx communication channel runs in standalone mode, it can be started in the main function. In the main function, you need to initialize logs and load service configuration. The code is as follow:
```java
import org.apache.servicecomb.foundation.common.utils.BeanUtils;
@@ -9,13 +9,13 @@
public class MainServer {
public static void main(String[] args) throws Exception {
- Log4jUtils.init();//Log initialization
+ Log4jUtils.init();// Log initialization
BeanUtils.init(); // Spring bean initialization
}
}
```
-To use the REST over Vertx communication channel, you need to add the following dependencies in the maven pom.xml file:
+To use the REST over Vertx communication channel, add the following dependencies in the maven pom.xml file:
```xml
<dependency>
@@ -24,23 +24,28 @@
</dependency>
```
-Configuration items that need to be set in the microservice.yaml file are described as follows:
+The REST over Vertx related configuration items in the microservice.yaml file are described as follows:
-Table 2 Configuration items of REST over Vertx
+Table 1-1 Configuration items for REST over Vertx
-| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
-| :--------------------------------------- | :------------ | :---------- | :-------- | :--------------------------------------- | :--------------------------------------- |
-| servicecomb.rest.address | 0.0.0.0:8080 | - | No | Specifies the server listening IP address. | Only service providers require this parameter. |
-| servicecomb.rest.server.thread-count | 1 | - | No | Specifies the number of server threads. | Only service providers require this parameter. |
-| servicecomb.rest.client.thread-count | 1 | - | No | Specifies the number of client network threads. | Only service consumers require this parameter. |
-| servicecomb.rest.client.connection-pool-per-thread | 1 | - | No | Specifies the number of connection pools in each client thread. | Only service consumers require this parameter. |
-| servicecomb.request.timeout | 30000 | - | No | Specifies the request timeout duration. | |
-| servicecomb.references.\[服务名\].transport | rest | | No | Specifies the accessed transport type. | Only service consumers require this parameter. |
-| servicecomb.references.\[服务名\].version-rule | latest | - | No | Specifies the version of the accessed instance. | Only service consumers require this parameter. You can set it to latest, a version range such as 1.0.0+ or 1.0.0-2.0.2, or a specific version number. For details, see the API description of the service center. |
+
+| Configuration Item | Default Value | Range | Required | Description | Remark |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| servicecomb.rest.address | 0.0.0.0:8080 | - | No | Service listening address | Only for providers |
+| servicecomb.rest.server.thread-count | 1 | - | No | Server's thread number | Only for providers |
+| servicecomb.rest.server.connection-limit | Integer.MAX_VALUE | - | No | Max allowed client connections | Only for providers |
+| servicecomb.rest.server.connection.idleTimeoutInSeconds | 60 | - | No | Timeout for server's idle connection | The idle connections will be recycled |
+| servicecomb.rest.client.thread-count | 1 | - | No | Client's thread number | Only for consumers |
+| servicecomb.rest.client.connection.maxPoolSize | 5 | - | No | Max connection number of each pool | connection number = thread number \* pool number \* pool connection number |
+| servicecomb.rest.client.connection.idleTimeoutInSeconds | 30 | - | No | The timeout of client idle connection| The idle connections will be recycled |
+| servicecomb.rest.client.connection.keepAlive | true | - | No | Use long lived connection or not | |
+| servicecomb.request.timeout | 30000 | - | No | Request timeout | |
+| servicecomb.references.\[ServiceName\].transport | rest | | No | The transport type to access | Only for consumers |
+| servicecomb.references.\[ServiceName\].version-rule | latest | - | No | The version of instance to access | Only for consumers. The supported rules including latest，1.0.0+，1.0.0-2.0.2，or accurate version. For details, please refer to the service center interface description |
### Sample Code
-An example of the configuration in the microservice.yaml file for REST over Vertx is as follows:
+An example of the configuration in the microservice.yaml file for REST over Vertx:
```yaml
servicecomb:
@@ -51,4 +56,5 @@
hello:
transport: rest
version-rule: 0.0.1
-```
\ No newline at end of file
+```
+
diff --git a/java-chassis-reference/en_US/build-provider/protocol/thread-model.md b/java-chassis-reference/en_US/build-provider/protocol/thread-model.md
index 16530e7..4356b01 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/thread-model.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/thread-model.md
@@ -1,22 +1,22 @@
## Thread Model
-### Concept Description
+### Concepts
-This section describes the thread model for ServiceComb microservices and the relationship between the I/O and service threads.
+This section describes ServiceComb's microservice thread model and the relationship between the I/O and service threads.
### Thread Model
-The complete thread model of CSE is shown in the following figure.
+The complete thread model of ServiceComb is shown below:
-> 1. When a service thread is called for the first time, it binds to a network thread to avoid thread conflicts caused by switching among different network threads.
-> 2. After the service thread bound to a network thread, it will bind to a connection of the network to avoid thread conflicts.
+> 1. When a service thread is called for the first time, it binds to a network thread to avoid thread conflicts caused by switching different network threads.
+> 2. After the binding to a network thread, the service thread will also bind to a connection of the network thread, to avoid thread conflicts.
-* Multiple network threads (eventloop) can be bound to both the client and the server. The number of network threads is two times the quantity of the CPU cores by default. Multiple connections can be configured for each network thread, and the default number is 1. The Rest and Highway network channels are supported. For details about these configurations, see following sections:
+* Multiple network threads (eventloop) can be bound to both client and server. The number of network threads is two times of the CPU cores by default. Multiple connections can be configured for each network thread, and the default connection number is 1. The Rest and Highway network channels are supported. For details about these configurations, see following sections:
* [REST over Servlet](/users/communicate-protocol#rest-over-servlet)
* [REST over Vertx](/users/communicate-protocol/#rest-over-vertx)
* [Highway RPC Protocol](/users/communicate-protocol/#highway-rpc协议)
-* You can configure the service thread pool executor for the client, and the thread granularity can be schemaId: operation.
+* You can configure the service thread pool executor for the server, the configuration can be applied to schemaId: operation.
Add the executors in the microservice.yaml file and configure an independent service thread pool for schemaId: operation:
