update parameter-binding doc

update parameter-binding doc

documentation20/cn/08.connector/01.java/docs.md

@@ -331,49 +331,238 @@ JDBC连接器可能报错的错误码包括3种：JDBC driver本身的报错（
 
 ### <a class="anchor" id="stmt-java"></a>通过参数绑定写入数据
 
-从 2.1.2.0 版本开始，TDengine 的 **JDBC-JNI** 实现大幅改进了参数绑定方式对数据写入（INSERT）场景的支持。采用这种方式写入数据时，能避免 SQL 语法解析的资源消耗，从而在很多情况下显著提升写入性能。（注意：**JDBC-RESTful** 实现并不提供参数绑定这种使用方式。）
-
+从 2.1.2.0 版本开始，TDengine 的 JDBC-JNI 实现大幅改进了参数绑定方式对数据写入（INSERT）场景的支持。采用这种方式写入数据时，能避免 SQL 语法解析的资源消耗，从而在很多情况下显著提升写入性能。
+注意：
+* JDBC-RESTful 实现并不提供参数绑定这种使用方式
+* 以下示例代码基于taos-jdbcdriver-2.0.36
+* binary类型数据需要调用setString方法，nchar类型数据需要调用setNString方法
+* setString 和 setNString 都要求用户在 size 参数里声明表定义中对应列的列宽
+
+示例代码：
 ```java
-Random r = new Random();
-
-// INSERT 语句中，VALUES 部分允许指定具体的数据列；如果采取自动建表，则 TAGS 部分需要设定全部 TAGS 列的参数值：
-TSDBPreparedStatement s = (TSDBPreparedStatement) conn.prepareStatement("insert into ? using weather_test tags (?, ?) (ts, c1, c2) values(?, ?, ?)");
-
-// 设定数据表名：
-s.setTableName("w1");
-// 设定 TAGS 取值：
-s.setTagInt(0, r.nextInt(10));
-s.setTagString(1, "Beijing");
-
-int numOfRows = 10;
-
-// VALUES 部分以逐列的方式进行设置：
-ArrayList<Long> ts = new ArrayList<>();
-for (int i = 0; i < numOfRows; i++){
-    ts.add(System.currentTimeMillis() + i);
-}
-s.setTimestamp(0, ts);
-
-ArrayList<Integer> s1 = new ArrayList<>();
-for (int i = 0; i < numOfRows; i++){
-    s1.add(r.nextInt(100));
-}
-s.setInt(1, s1);
-
-ArrayList<String> s2 = new ArrayList<>();
-for (int i = 0; i < numOfRows; i++){
-    s2.add("test" + r.nextInt(100));
+public class ParameterBindingDemo {
+ 
+    private static final String host = "127.0.0.1";
+    private static final Random random = new Random(System.currentTimeMillis());
+    private static final int BINARY_COLUMN_SIZE = 20;
+    private static final String[] schemaList = {
+            "create table stable1(ts timestamp, f1 tinyint, f2 smallint, f3 int, f4 bigint) tags(t1 tinyint, t2 smallint, t3 int, t4 bigint)",
+            "create table stable2(ts timestamp, f1 float, f2 double) tags(t1 float, t2 double)",
+            "create table stable3(ts timestamp, f1 bool) tags(t1 bool)",
+            "create table stable4(ts timestamp, f1 binary(" + BINARY_COLUMN_SIZE + ")) tags(t1 binary(" + BINARY_COLUMN_SIZE + "))",
+            "create table stable5(ts timestamp, f1 nchar(" + BINARY_COLUMN_SIZE + ")) tags(t1 nchar(" + BINARY_COLUMN_SIZE + "))"
+    };
+    private static final int numOfSubTable = 10, numOfRow = 10;
+ 
+    public static void main(String[] args) throws SQLException {
+ 
+        String jdbcUrl = "jdbc:TAOS://" + host + ":6030/";
+        Connection conn = DriverManager.getConnection(jdbcUrl, "root", "taosdata");
+ 
+        init(conn);
+ 
+        bindInteger(conn);
+ 
+        bindFloat(conn);
+ 
+        bindBoolean(conn);
+ 
+        bindBytes(conn);
+ 
+        bindString(conn);
+ 
+        conn.close();
+    }
+ 
+    private static void init(Connection conn) throws SQLException {
+        try (Statement stmt = conn.createStatement()) {
+            stmt.execute("drop database if exists test_parabind");
+            stmt.execute("create database if not exists test_parabind");
+            stmt.execute("use test_parabind");
+            for (int i = 0; i < schemaList.length; i++) {
+                stmt.execute(schemaList[i]);
+            }
+        }
+    }
+ 
+    private static void bindInteger(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable1 tags(?,?,?,?) values(?,?,?,?,?)";
+ 
+        try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) {
+ 
+            for (int i = 1; i <= numOfSubTable; i++) {
+                // set table name
+                pstmt.setTableName("t1_" + i);
+                // set tags
+                pstmt.setTagByte(0, Byte.parseByte(Integer.toString(random.nextInt(Byte.MAX_VALUE))));
+                pstmt.setTagShort(1, Short.parseShort(Integer.toString(random.nextInt(Short.MAX_VALUE))));
+                pstmt.setTagInt(2, random.nextInt(Integer.MAX_VALUE));
+                pstmt.setTagLong(3, random.nextLong());
+                // set columns
+                ArrayList<Long> tsList = new ArrayList<>();
+                long current = System.currentTimeMillis();
+                for (int j = 0; j < numOfRow; j++)
+                    tsList.add(current + j);
+                pstmt.setTimestamp(0, tsList);
+ 
+                ArrayList<Byte> f1List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f1List.add(Byte.parseByte(Integer.toString(random.nextInt(Byte.MAX_VALUE))));
+                pstmt.setByte(1, f1List);
+ 
+                ArrayList<Short> f2List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f2List.add(Short.parseShort(Integer.toString(random.nextInt(Short.MAX_VALUE))));
+                pstmt.setShort(2, f2List);
+ 
+                ArrayList<Integer> f3List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f3List.add(random.nextInt(Integer.MAX_VALUE));
+                pstmt.setInt(3, f3List);
+ 
+                ArrayList<Long> f4List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f4List.add(random.nextLong());
+                pstmt.setLong(4, f4List);
+ 
+                // add column
+                pstmt.columnDataAddBatch();
+            }
+            // execute column
+            pstmt.columnDataExecuteBatch();
+        }
+    }
+ 
+    private static void bindFloat(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable2 tags(?,?) values(?,?,?)";
+ 
+        TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class);
+ 
+        for (int i = 1; i <= numOfSubTable; i++) {
+            // set table name
+            pstmt.setTableName("t2_" + i);
+            // set tags
+            pstmt.setTagFloat(0, random.nextFloat());
+            pstmt.setTagDouble(1, random.nextDouble());
+            // set columns
+            ArrayList<Long> tsList = new ArrayList<>();
+            long current = System.currentTimeMillis();
+            for (int j = 0; j < numOfRow; j++)
+                tsList.add(current + j);
+            pstmt.setTimestamp(0, tsList);
+ 
+            ArrayList<Float> f1List = new ArrayList<>();
+            for (int j = 0; j < numOfRow; j++)
+                f1List.add(random.nextFloat());
+            pstmt.setFloat(1, f1List);
+ 
+            ArrayList<Double> f2List = new ArrayList<>();
+            for (int j = 0; j < numOfRow; j++)
+                f2List.add(random.nextDouble());
+            pstmt.setDouble(2, f2List);
+ 
+            // add column
+            pstmt.columnDataAddBatch();
+        }
+        // execute
+        pstmt.columnDataExecuteBatch();
+        // close if no try-with-catch statement is used
+        pstmt.close();
+    }
+ 
+    private static void bindBoolean(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable3 tags(?) values(?,?)";
+ 
+        try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) {
+            for (int i = 1; i <= numOfSubTable; i++) {
+                // set table name
+                pstmt.setTableName("t3_" + i);
+                // set tags
+                pstmt.setTagBoolean(0, random.nextBoolean());
+                // set columns
+                ArrayList<Long> tsList = new ArrayList<>();
+                long current = System.currentTimeMillis();
+                for (int j = 0; j < numOfRow; j++)
+                    tsList.add(current + j);
+                pstmt.setTimestamp(0, tsList);
+ 
+                ArrayList<Boolean> f1List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++)
+                    f1List.add(random.nextBoolean());
+                pstmt.setBoolean(1, f1List);
+ 
+                // add column
+                pstmt.columnDataAddBatch();
+            }
+            // execute
+            pstmt.columnDataExecuteBatch();
+        }
+    }
+ 
+    private static void bindBytes(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable4 tags(?) values(?,?)";
+ 
+        try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) {
+ 
+            for (int i = 1; i <= numOfSubTable; i++) {
+                // set table name
+                pstmt.setTableName("t4_" + i);
+                // set tags
+                pstmt.setTagString(0, new String("abc"));
+ 
+                // set columns
+                ArrayList<Long> tsList = new ArrayList<>();
+                long current = System.currentTimeMillis();
+                for (int j = 0; j < numOfRow; j++)
+                    tsList.add(current + j);
+                pstmt.setTimestamp(0, tsList);
+ 
+                ArrayList<String> f1List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++) {
+                    f1List.add(new String("abc"));
+                }
+                pstmt.setString(1, f1List, BINARY_COLUMN_SIZE);
+ 
+                // add column
+                pstmt.columnDataAddBatch();
+            }
+            // execute
+            pstmt.columnDataExecuteBatch();
+        }
+    }
+ 
+    private static void bindString(Connection conn) throws SQLException {
+        String sql = "insert into ? using stable5 tags(?) values(?,?)";
+ 
+        try (TSDBPreparedStatement pstmt = conn.prepareStatement(sql).unwrap(TSDBPreparedStatement.class)) {
+ 
+            for (int i = 1; i <= numOfSubTable; i++) {
+                // set table name
+                pstmt.setTableName("t5_" + i);
+                // set tags
+                pstmt.setTagNString(0, "北京-abc");
+ 
+                // set columns
+                ArrayList<Long> tsList = new ArrayList<>();
+                long current = System.currentTimeMillis();
+                for (int j = 0; j < numOfRow; j++)
+                    tsList.add(current + j);
+                pstmt.setTimestamp(0, tsList);
+ 
+                ArrayList<String> f1List = new ArrayList<>();
+                for (int j = 0; j < numOfRow; j++) {
+                    f1List.add("北京-abc");
+                }
+                pstmt.setNString(1, f1List, BINARY_COLUMN_SIZE);
+ 
+                // add column
+                pstmt.columnDataAddBatch();
+            }
+            // execute
+            pstmt.columnDataExecuteBatch();
+        }
+    }
 }
-s.setString(2, s2, 10);
-
-// AddBatch 之后，缓存并未清空。为避免混乱，并不推荐在 ExecuteBatch 之前再次绑定新一批的数据：
-s.columnDataAddBatch();
-// 执行绑定数据后的语句：
-s.columnDataExecuteBatch();
-// 执行语句后清空缓存。在清空之后，可以复用当前的对象，绑定新的一批数据（可以是新表名、新 TAGS 值、新 VALUES 值）：
-s.columnDataClearBatch();
-// 执行完毕，释放资源：
-s.columnDataCloseBatch();
 ```
 
 用于设定 TAGS 取值的方法总共有：
@@ -405,8 +594,6 @@ public void setString(int columnIndex, ArrayList<String> list, int size) throws
 public void setNString(int columnIndex, ArrayList<String> list, int size) throws SQLException
 ```
 
-其中 setString 和 setNString 都要求用户在 size 参数里声明表定义中对应列的列宽。
-
 ## <a class="anchor" id="subscribe"></a>订阅
 
 ### 创建