Merge pull request #3857 from taosdata/zyyang-taosdata-patch-3

Update connector-java-ch.md

documentation20/webdocs/markdowndocs/connector-java-ch.md

@@ -72,38 +72,35 @@ maven 项目中使用如下 pom.xml 配置即可：
 
 ### 获取连接
 
-如下所示配置即可获取 TDengine Connection：
+#### 通过JdbcUrl获取连接
+
+通过指定的jdbcUrl获取连接，如下所示：
 ```java
 Class.forName("com.taosdata.jdbc.TSDBDriver");
-String jdbcUrl = "jdbc:TAOS://127.0.0.1:6030/log?user=root&password=taosdata";
+String jdbcUrl = "jdbc:TAOS://taosdemo.com:6030/log?user=root&password=taosdata";
 Connection conn = DriverManager.getConnection(jdbcUrl);
 ```
-> 端口 6030 为默认连接端口，JDBC URL 中的 log 为系统本身的监控数据库。
+以上示例，建立了到hostname为taosdemo.com，端口为6030，database为log的连接。
+> 端口 6030 为默认连接端口，JDBC URL 中的 log 为系统本身的监控数据库，user和password参数指定了用户名和密码
 
 TDengine 的 JDBC URL 规范格式为：
-`jdbc:TAOS://{host_ip}:{port}/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]`
-
-其中，`{}` 中的内容必须，`[]` 中为可选。配置参数说明如下：
-
+`jdbc:TAOS://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]`
+url中的配置参数如下：
 * user：登录 TDengine 用户名，默认值 root。
 * password：用户登录密码，默认值 taosdata。
-* charset：客户端使用的字符集，默认值为系统字符集。
 * cfgdir：客户端配置文件目录路径，Linux OS 上默认值 /etc/taos ，Windows OS 上默认值 C:/TDengine/cfg。
+* charset：客户端使用的字符集，默认值为系统字符集。
 * locale：客户端语言环境，默认值系统当前 locale。
 * timezone：客户端使用的时区，默认值为系统当前时区。
 
-以上参数可以在 3 处配置，`优先级由高到低`分别如下：
-1. JDBC URL 参数
-    如上所述，可以在 JDBC URL 的参数中指定。
-2. java.sql.DriverManager.getConnection(String jdbcUrl, Properties connProps)
+#### 使用JdbcUrl和Properties获取连接
+
+除了通过指定的jdbcUrl获取连接，还可以使用Properties指定建立连接时的参数，如下所示：
 ```java
 public Connection getConn() throws Exception{
   Class.forName("com.taosdata.jdbc.TSDBDriver");
-  String jdbcUrl = "jdbc:TAOS://127.0.0.1:0/log?user=root&password=taosdata";
+  String jdbcUrl = "jdbc:TAOS://taosdemo.com:6030/log?user=root&password=taosdata";
   Properties connProps = new Properties();
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_USER, "root");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_PASSWORD, "taosdata");
-  connProps.setProperty(TSDBDriver.PROPERTY_KEY_CONFIG_DIR, "/etc/taos");
   connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
   connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
   connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");
@@ -111,16 +108,39 @@ public Connection getConn() throws Exception{
   return conn;
 }
 ```
+以上示例，建立一个到hostname为taosdemo.com，端口为6030，数据库为log的连接。这个连接在jdbcUrl中指定了用户名和密码，并在connProps中指定了使用的字符集、语言环境、时区等信息。
+
+properties中的配置参数如下：
+* TSDBDriver.PROPERTY_KEY_USER：登录 TDengine 用户名，默认值 root。
+* TSDBDriver.PROPERTY_KEY_PASSWORD：用户登录密码，默认值 taosdata。
+* TSDBDriver.PROPERTY_KEY_CONFIG_DIR：客户端配置文件目录路径，Linux OS 上默认值 /etc/taos ，Windows OS 上默认值 C:/TDengine/cfg。
+* TSDBDriver.PROPERTY_KEY_CHARSET：客户端使用的字符集，默认值为系统字符集。
+* TSDBDriver.PROPERTY_KEY_LOCALE：客户端语言环境，默认值系统当前 locale。
+* TSDBDriver.PROPERTY_KEY_TIME_ZONE：客户端使用的时区，默认值为系统当前时区。
+
+#### 使用客户端配置文件建立连接
+当使用JDBC连接TDengine集群时，可以使用客户端配置文件，在客户端配置文件中指定集群的firstEp、SecondEp参数。
+如下所示：
+1. 在java中不指定hostname和port
+```java
+public Connection getConn() throws Exception{
+  Class.forName("com.taosdata.jdbc.TSDBDriver");
+  String jdbcUrl = "jdbc:TAOS://:/log?user=root&password=taosdata";
+  Properties connProps = new Properties();
+  connProps.setProperty(TSDBDriver.PROPERTY_KEY_CHARSET, "UTF-8");
+  connProps.setProperty(TSDBDriver.PROPERTY_KEY_LOCALE, "en_US.UTF-8");
+  connProps.setProperty(TSDBDriver.PROPERTY_KEY_TIME_ZONE, "UTC-8");
+  Connection conn = DriverManager.getConnection(jdbcUrl, connProps);
+  return conn;
+}
+```
+2. 在配置文件中指定firstEp和secondEp
+```
+# first fully qualified domain name (FQDN) for TDengine system
+firstEp               cluster_node1:6030
 
-3. 客户端配置文件 taos.cfg
-
-    linux 系统默认配置文件为 /var/lib/taos/taos.cfg，windows 系统默认配置文件路径为 C:\TDengine\cfg\taos.cfg。
-```properties
-# client default username
-# defaultUser           root
-
-# client default password
-# defaultPass           taosdata
+# second fully qualified domain name (FQDN) for TDengine system, for cluster only
+secondEp              cluster_node2:6030
 
 # default system charset
 # charset               UTF-8
@@ -128,6 +148,19 @@ public Connection getConn() throws Exception{
 # system locale
 # locale                en_US.UTF-8
 ```
+
+以上示例，jdbc会使用客户端的配置文件，建立到hostname为cluster_node1，端口为6030的连接。当集群中firstEp节点失效时，JDBC会尝试使用secondEp连接集群。
+TDengine中，只要firstEp和secondEp中任何一个节点为有效连接，TDengine就可以通过该节点，找到集群的master。因此，只要保证firstEp和secondEp中一个节点有效，就可以正常建立到集群的连接。
+
+> 注意：这里的配置文件指的是调用JDBC Connector的应用程序所在的机器上的配置文件，Linux OS 上默认值 /etc/taos ，Windows OS 上默认值 C:/TDengine/cfg。
+
+#### 配置参数的优先级
+通过以上3种方式获取连接，如果配置参数在url、Properties、客户端配置文件中有重复，则参数的`优先级由高到低`分别如下：
+1. JDBC URL 参数，如上所述，可以在 JDBC URL 的参数中指定。
+2. Properties connProps
+3. 客户端配置文件 taos.cfg
+例如：在url中指定了password为taosdata，在Properties中指定了password为taosdemo，那么，JDBC会使用url中的password建立连接。
+
 > 更多详细配置请参考[客户端配置][13]
 
 ### 创建数据库和表