docs: 更新 UpsertSession 初始化文档并添加示例代码

dingxin-tech · dingxin-tech · commit f6db44a66c9b · 2024-09-06T11:25:04.000+08:00
diff --git a/.gitignore b/.gitignore
@@ -2,10 +2,34 @@
 .classpath
 .project
 *.iml
-.idea
 target/
 .DS_Store
 *.pyc
 replace_config.sh
 ajcore.*
 .vscode/
+
+# Dependencies
+/docs/node_modules
+
+# Production
+/docs/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# IDE
+.idea
+.idea/*
diff --git a/docs/docs/api-reference/tunnel/TableTunnel.md b/docs/docs/api-reference/tunnel/TableTunnel.md
@@ -15,7 +15,7 @@ sidebar_position: 3
 
 - `StreamUploadSession`
 - `UploadSession`
-- `UpsertSession`
+- [UpsertSession](#初始化upsertsession)
 
 用户可以根据业务需求选择不同的写入类，以满足不同场景下的需求。下面提供了一个快速选择写入类的流程图。
 
@@ -81,15 +81,29 @@ sidebar_position: 3
 ### 待完善
 
 ## 初始化
-### 待完善
 
-在使用 `TableTunnel` 之前，需要进行初始化操作，包括设置访问ID、访问密钥、ODPS和Tunnel的端点等。
+在使用 `TableTunnel` 之前，需要进行 Odps 对象的初始化操作，对 Odps 对象的初始化操作参考[初始化 Odps 对象](../../example-code/init-odps-client.md)。
+
+根据是否需要自定义TableTunnel的配置，可以使用如下两个接口来初始化TableTunnel。
+
+**无参初始化**
+```java
+TableTunnel tunnel = odps.tableTunnel();
+```
+
+**使用配置文件进行初始化**
+```java
+// com.aliyun.odps.tunnel.Configuration;
+Configuration configuration=Configuration.builder(odps).build();
+TableTunnel tunnel = odps.tableTunnel(configuration);
+```
+有关配置文件的配置项，请参考[Configuration 文档](Configuration.md)。
+
+
+## 初始化UpsertSession
 
+`TableTunnel` 提供了 `buildUpsertSession` 方法来初始化一个 Upsert 会话的 Builder。
 ```java
-Account account = new AliyunAccount("<your access id>", "<your access key>");
-Odps odps = new Odps(account);
-odps.setEndpoint("<your odps endpoint>");
-odps.setDefaultProject("<your project>");
-TableTunnel tunnel = new TableTunnel(odps);
-tunnel.setEndpoint("<your tunnel endpoint>");
+TableTunnel.UpsertSession.Builder buildUpsertSession(String projectName, String tableName);
 ```
+有关 Upsert 会话 Builder 的使用方法和全部配置项，请参考[UpsertSession 初始化](UpsertSession.md#builder-接口)。
diff --git a/docs/docs/api-reference/tunnel/UpsertSession.md b/docs/docs/api-reference/tunnel/UpsertSession.md
@@ -3,29 +3,32 @@ title: UpsertSession
 sidebar_position: 4
 ---
 
-# UpsertSession 接口文档
+# UpsertSession
 
 ## 概述
 
 `UpsertSession` 接口用于管理和操作数据插入或更新的会话。通过该接口，用户可以获取会话的相关信息、提交或中止会话、创建新的记录对象等。
 
-## 方法
+## 初始化
+通常由[TableTunnel#buildUpsertSession](TableTunnel.md#初始化upsertsession)方法创建 Builder，
+[Builder接口](UpsertSession.md#builder-接口)的build方法来构建 UpsertSession。
 
+## 方法
 ### 获取Session ID
 
 ```java
 String getId();
 ```
 
-返回当前会话的ID。
+返回当前会话的ID，可以基于这个ID进行重建会话操作。
 
 ### 获取当前 Quota
 
 ```java
 public String getQuotaName();
 ```
 
-返回当前的配额名称。
+返回当前使用的Quota名称，注意不是QuotaNickName。
 
 ### 获取Session状态
 
@@ -34,20 +37,20 @@ String getStatus() throws TunnelException;
 ```
 
 返回当前会话的状态码，可能的状态包括：
-- normal
-- committing
-- committed
-- expired
-- critical
-- aborted
+- normal 正常
+- committing 提交中
+- committed 已提交
+- expired 过期
+- critical 错误
+- aborted 已中止
 
 ### 获取表结构
 
 ```java
 TableSchema getSchema();
 ```
 
-返回当前会话的表结构。
+返回当前会话写入的表的表结构。
 
 ### 提交UpsertSession
 
@@ -56,6 +59,7 @@ void commit(boolean async) throws TunnelException;
 ```
 
 提交当前会话。可以选择是否异步提交。
+当选择异步提交时，提交操作像服务端发送提交请求后立即返回，不会等待数据提交完成，这也意味着数据不会立即可见。
 
 ### 中止UpsertSession
 
@@ -81,6 +85,9 @@ Record newRecord();
 
 创建并返回一个新的 `Record` 对象。
 
+这个`Record`是`UpsertRecord`的实例，这个实例包含执行upsert操作必要的一些信息。
+因此当使用Upsert操作时，永远记得使用这个方法，来获取`Record`的实例。
+
 ### 构建UpsertStream
 
 ```java
@@ -89,10 +96,14 @@ UpsertStream.Builder buildUpsertStream();
 
 返回一个用于构建 `UpsertStream` 的 `Builder` 对象。
 
+`UpsertStream` 是用于执行数据插入或更新操作的核心接口，详见 [UpsertStream 接口文档](UpsertStream.md)。
+
 ## Builder 接口
 
 `UpsertSession.Builder` 接口用于构建 `UpsertSession` 对象。
 
+通常由[TableTunnel#buildUpsertSession](TableTunnel.md#初始化upsertsession) 方法创建。
+
 ### 获取和设置Upsert ID
 
 ```java
@@ -139,7 +150,7 @@ UpsertSession.Builder setCommitTimeout(long commitTimeoutMs);
 
 获取和设置提交超时时间（毫秒）。
 
-### 设置网络线程数
+### 设置Netty进行网络IO的线程数
 
 ```java
 UpsertSession.Builder setNetworkThreadNum(int threadNum);
@@ -178,7 +189,7 @@ long getLifecycle();
 UpsertSession.Builder setLifecycle(long lifecycle);
 ```
 
-获取和设置Session生命周期（小时），有效值域为1 - 24，指定有效值域以外的值该参数会被忽略，使用服务端默认值。
+获取和设置Session生命周期（小时），有效取值范围为1 - 24，指定有效取值范围以外的值该参数会被忽略，使用服务端默认值。
 
 ### 构建UpsertSession
 
diff --git a/docs/docs/api-reference/tunnel/UpsertStream.md b/docs/docs/api-reference/tunnel/UpsertStream.md
@@ -1,13 +1,14 @@
 ---
-title: UpsertStreamImpl
+title: UpsertStream
 sidebar_position: 5
 ---
 
-# UpsertStream 类文档
+# UpsertStream
 
 ## 概述
 
-在当前版本，`UpsertStreamImpl` 类是 `UpsertStream`接口唯一的实现类，因此本文主要介绍`UpsertStreamImpl`的类接口。
+在当前版本，`UpsertStreamImpl` 类是 `UpsertStream`接口唯一的实现类，因此本文主要介绍`UpsertStreamImpl`
+的类接口。
 通过该类，用户可以对`Delta Table`进行数据的插入、更新、删除操作，并支持数据的缓冲和批量提交。
 
 ## 构造方法
@@ -27,16 +28,18 @@ public UpsertStreamImpl(Builder builder)throws IOException,TunnelException
 
 ```java
 @Override
-public void upsert(Record record) throws IOException,TunnelException
+public void upsert(Record record)throws IOException,TunnelException
 ```
 
 插入或更新一条记录。
 
 参数列表：
-record：**注：参数`record`应当是`UpsertRecord`的实例**，这个实例可以通过 [`UpsertSession#newRecord()`](UpsertSession.md#创建一个record对象) 方法创建。
+record：**注：参数`record`应当是`UpsertRecord`的实例**
+，这个实例可以通过 [`UpsertSession#newRecord()`](UpsertSession.md#创建一个record对象) 方法创建。
 
+:::info
 `UpsertRecord`内部维护了一些元数据隐藏列，因此用户不应当手动创建`ArrayRecord`对象将其传入。
-
+:::
 
 ### 插入或更新部分列
 
@@ -47,7 +50,8 @@ public void upsert(Record record,List<String> upsertCols)throws IOException,Tunn
 
 插入或更新一条记录的部分列。
 
-record : `UpsertRecord`的实例，这个实例可以通过 [`UpsertSession#newRecord()`](UpsertSession.md#创建一个record对象) 方法创建。
+record : `UpsertRecord`
+的实例，这个实例可以通过 [`UpsertSession#newRecord()`](UpsertSession.md#创建一个record对象) 方法创建。
 
 upsertCols : 一个包含要更新的列名的列表。
 
@@ -60,7 +64,8 @@ public void delete(Record record)throws IOException,TunnelException
 
 删除一条记录。
 
-record : `UpsertRecord`的实例，这个实例可以通过 [`UpsertSession#newRecord()`](UpsertSession.md#创建一个record对象) 方法创建。
+record : `UpsertRecord`
+的实例，这个实例可以通过 [`UpsertSession#newRecord()`](UpsertSession.md#创建一个record对象) 方法创建。
 
 ### 刷新缓冲区
 
@@ -89,24 +94,116 @@ public void reset()throws IOException
 
 重置缓冲区，清空所有未提交的数据。
 
+## 重试逻辑
+
+UpsertStream 通过用户传入 `Listener` 监听器来处理重试逻辑。当用户不传入 `Listener` 时，UpsertStream
+将使用一个默认的 `Listener` 实例(`UpsertSessionImpl.DefaultUpsertSteamListener`)
+
+这个默认的`Listener`实例，遵循`TableTunnel`默认的[重试逻辑](RetryLogic.md)。
+
+:::tip
+十分推荐当用户实现自定义`Listener`时，继承`UpsertSessionImpl.DefaultUpsertSteamListener`
+，以使`TableTunnel`的重试逻辑生效。
+:::
+
 
 ## Builder 类
 
-`UpsertStreamImpl.Builder` 类用于构建 `UpsertStreamImpl` 对象。通常由 [`UpsertSession#buildUpsertStream()`](UpsertSession.md#构建upsertstream) 方法调用。
-
-### 方法
-
-- `public Builder setSession(UpsertSessionImpl session)` 
-- `public UpsertSessionImpl getSession()`
-- `public long getMaxBufferSize()`
-- `public Builder setMaxBufferSize(long maxBufferSize)`
-- `public long getSlotBufferSize()`
-- `public Builder setSlotBufferSize(long slotBufferSize)`
-- `@Override public CompressOption getCompressOption()`
-- `@Override public Builder setCompressOption(CompressOption compressOption)`
-- `@Override public Listener getListener()`
-- `@Override public Builder setListener(Listener listener)`
-- `@Override public UpsertStream build() throws IOException, TunnelException`
+`UpsertStreamImpl.Builder` 类是构建 `UpsertStreamImpl` 实例的基石，它提供了灵活的配置选项以便用户根据需求定制 `UpsertStream` 的行为。
+此构造器主要通过 [`UpsertSession#buildUpsertStream()`](UpsertSession.md#构建upsertstream) 方法被调用，允许用户在创建 `UpsertStream` 时精确控制多个参数，
+以优化数据插入或更新的性能和资源使用。
+
+### 方法详情
+
+#### 设置会话对象
+
+- **方法签名**:
+  ```java
+  public Builder setSession(UpsertSessionImpl session)
+  ```
+- **功能说明**:
+  为 `UpsertStream` 指定关联的 `UpsertSessionImpl` 实例。这是UpsertSession#buildUpsertStream()的默认步骤，通常不需要用户手动调用。 
+
+#### 获取会话对象
+
+- **方法签名**:
+  ```java
+  public UpsertSessionImpl getSession()
+  ```
+- **功能说明**:
+  返回已设置的 `UpsertSessionImpl` 实例，供外部查询或验证使用。
+
+#### 设置最大缓冲区大小
+
+- **方法签名**:
+  ```java
+  public Builder setMaxBufferSize(long maxBufferSize)
+  ```
+- **功能说明**:
+  允许用户设定数据缓冲的最大容量（单位：字节）。这直接影响到内存使用和批量写入的效率，较大的缓冲区可以减少I/O操作次数，但会占用更多内存。
+
+#### 获取最大缓冲区大小
+
+- **方法签名**:
+  ```java
+  public long getMaxBufferSize()
+  ```
+- **功能说明**:
+  查询当前设置的最大缓冲区大小。
+
+#### 设置槽缓冲区大小
+
+- **方法签名**:
+  ```java
+  public Builder setSlotBufferSize(long slotBufferSize)
+  ```
+- **功能说明**:
+  为每个桶设置缓冲区大小（单位：字节）。
+
+#### 获取槽缓冲区大小
+
+- **方法签名**:
+  ```java
+  public long getSlotBufferSize()
+  ```
+- **功能说明**:
+  获取当前设置的每个桶的缓冲区大小。
+
+#### 压缩选项配置
+
+- **获取压缩选项**:
+  ```java
+  @Override public CompressOption getCompressOption()
+  ```
+- **设置压缩选项**:
+  ```java
+  @Override public Builder setCompressOption(CompressOption compressOption)
+  ```
+- **功能说明**:
+  控制数据在传输前的压缩策略。通过选择合适的压缩算法，可以在减少网络传输成本和存储空间的同时，可能会增加一定的CPU使用。
+
+#### 设置监听器
+
+- **获取监听器**:
+  ```java
+  @Override public Listener getListener()
+  ```
+- **设置监听器**:
+  ```java
+  @Override public Builder setListener(Listener listener)
+  ```
+- **功能说明**:
+  注册一个监听器，用于接收 `UpsertStream` 在数据写入过程中的事件通知，和重试逻辑的配置。UpsertSession#buildUpsertStream() 方法会为 UpsertStream 配置一个默认的 Listener 实例。详情参考[重试逻辑](#重试逻辑)
+
+
+#### 构建 UpsertStream 实例
+
+- **方法签名**:
+  ```java
+  @Override public UpsertStream build() throws IOException, TunnelException
+  ```
+- **功能说明**:
+  根据之前设置的所有配置项构建并返回一个 `UpsertStream` 实例。
 
 ## 总结
 
diff --git a/docs/docs/example-code/upsert.md b/docs/docs/example-code/upsert.md
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
