This is an automated email from the ASF dual-hosted git repository.
zhangliang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/shardingsphere.git
The following commit(s) were added to refs/heads/master by this push:
new 2956201 xa transaction doc (#8630)
2956201 is described below
commit 295620120f5a1dc2a5836b126d7a1f7fcb64e179
Author: xiaoyu <[email protected]>
AuthorDate: Tue Dec 15 23:14:55 2020 +0800
xa transaction doc (#8630)
---
.../shardingsphere-jdbc/configuration/props.cn.md | 1 +
.../shardingsphere-jdbc/configuration/props.en.md | 1 +
.../usage/transaction/narayana.cn.md | 88 +++++++++++++++++++++
.../usage/transaction/narayana.en.md | 89 ++++++++++++++++++++++
.../usage/transaction/seata.cn.md | 2 +-
.../usage/transaction/seata.en.md | 2 +-
.../shardingsphere-proxy/configuration/props.cn.md | 1 +
.../shardingsphere-proxy/configuration/props.en.md | 1 +
.../shardingsphere-proxy/usage/transaction.cn.md | 45 ++++++++++-
.../shardingsphere-proxy/usage/transaction.en.md | 50 ++++++++++++
10 files changed, 277 insertions(+), 3 deletions(-)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/configuration/props.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/configuration/props.cn.md
index e3d18f4..ee9ba9b 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/configuration/props.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/configuration/props.cn.md
@@ -18,3 +18,4 @@ Apache ShardingSphere 提供属性配置的方式配置系统级配置。
| max-connections-size-per-query (?) | int |
一次查询请求在每个数据库实例中所能使用的最大连接数。
| 1 |
| check-table-metadata-enabled (?) | boolean | 是否在程序启动和更新时检查分片元数据的结构一致性。
| false |
| query-with-cipher-column (?) | boolean |
是否使用加密列进行查询。在有原文列的情况下，可以使用原文列进行查询。
|
true |
+| transaction-manager-type (?) | String |
事务管理器类型。列如：atomikos，narayana
| atomikos |
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/configuration/props.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/configuration/props.en.md
index 485e293..d7fbe30 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/configuration/props.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/configuration/props.en.md
@@ -18,3 +18,4 @@ Apache ShardingSphere provides the way of property
configuration to configure sy
| max-connections-size-per-query (?) | int | Max opened connection
size for each query.
| 1
|
| check-table-metadata-enabled (?) | boolean | Whether validate table
meta data consistency when application startup or updated.
| false
|
| query-with-cipher-column (?) | boolean | Whether query with cipher
column for data encrypt. User you can use plaintext to query if have.
| true
|
+| transaction-manager-type (?) | String | ShardingSphere
transaction manager type. Include: atomikos, narayana.
|
atomikos |
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/narayana.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/narayana.cn.md
new file mode 100644
index 0000000..0cff74d
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/narayana.cn.md
@@ -0,0 +1,88 @@
++++
+title = "Narayana 事务"
+weight = 5
++++
+
+## 引入 Maven 依赖
+
+```xml
+<propeties>
+ <narayana.version>5.9.1.Final</narayana.version>
+
<jboss-transaction-spi.version>7.6.0.Final</jboss-transaction-spi.version>
+ <jboss-logging.version>3.2.1.Final</jboss-logging.version>
+</propeties>
+
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+</dependency>
+
+<!-- 使用 XA 事务时，需要引入此模块 -->
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-transaction-xa-core</artifactId>
+ <version>${shardingsphere.version}</version>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-transaction-xa-narayana</artifactId>
+ <version>${shardingsphere.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.narayana.jta</groupId>
+ <artifactId>jta</artifactId>
+ <version>${narayana.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.narayana.jts</groupId>
+ <artifactId>narayana-jts-integration</artifactId>
+ <version>${narayana.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jboss-transaction-spi</artifactId>
+ <version>${jboss-transaction-spi.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.logging</groupId>
+ <artifactId>jboss-logging</artifactId>
+ <version>${jboss-logging.version}</version>
+</dependency>
+```
+
+## 修改配置
+
+可以通过在项目的 classpath 中添加 `jbossts-properties.xml` 来定制化 Narayana 配置项。
+
+详情请参见[Narayana官方文档](https://narayana.io/documentation/index.html)。
+
+## 设置XA事务管理类型
+
+在Apache ShardingSphere 配置系统级配置中设置XA事务管理器类型。
+
+Yaml:
+```yaml
+props:
+ transaction-manager-type: narayana
+```
+
+Spring-Boot:
+
+```yaml
+spring:
+ shardingsphere:
+ props:
+ transaction-manager-type: narayana
+```
+
+Spring-Namespace:
+
+```xml
+<shardingsphere:data-source id="xxx" data-source-names="xxx" rule-refs="xxx">
+ <props>
+ <prop key="transaction-manager-type">narayana</prop>
+ </props>
+</shardingsphere:data-source>
+```
\ No newline at end of file
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/narayana.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/narayana.en.md
new file mode 100644
index 0000000..8fb406f
--- /dev/null
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/narayana.en.md
@@ -0,0 +1,89 @@
++++
+title = "Narayana Transaction"
+weight = 5
++++
+
+## Import Maven Dependency
+
+```xml
+<propeties>
+ <narayana.version>5.9.1.Final</narayana.version>
+
<jboss-transaction-spi.version>7.6.0.Final</jboss-transaction-spi.version>
+ <jboss-logging.version>3.2.1.Final</jboss-logging.version>
+</propeties>
+
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+</dependency>
+
+<!-- import if using XA transaction -->
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-transaction-xa-core</artifactId>
+ <version>${shardingsphere.version}</version>
+</dependency>
+
+<dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-transaction-xa-narayana</artifactId>
+ <version>${shardingsphere.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.narayana.jta</groupId>
+ <artifactId>jta</artifactId>
+ <version>${narayana.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.narayana.jts</groupId>
+ <artifactId>narayana-jts-integration</artifactId>
+ <version>${narayana.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jboss-transaction-spi</artifactId>
+ <version>${jboss-transaction-spi.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.logging</groupId>
+ <artifactId>jboss-logging</artifactId>
+ <version>${jboss-logging.version}</version>
+</dependency>
+```
+
+## Update Configuration
+
+Developer can add `jbossts-properties.xml` in classpath of the application to
customize Narayana configuration.
+For detailed configuration rules.
+
+Please refer to [Narayana official
documentation](https://narayana.io/documentation/index.html) for more details.
+
+## Config Transaction Manager Type
+
+Set the XA transaction manager type in the Apache ShardingSphere configuration
system-level configuration.
+
+Yaml:
+```yaml
+props:
+ transaction-manager-type: narayana
+```
+
+Spring-Boot:
+
+```yaml
+spring:
+ shardingsphere:
+ props:
+ transaction-manager-type: narayana
+```
+
+Spring-Namespace:
+
+```xml
+<shardingsphere:data-source id="xxx" data-source-names="xxx" rule-refs="xxx">
+ <props>
+ <prop key="transaction-manager-type">narayana</prop>
+ </props>
+</shardingsphere:data-source>
+```
\ No newline at end of file
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/seata.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/seata.cn.md
index 615e974..75c9d23 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/seata.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/seata.cn.md
@@ -1,6 +1,6 @@
+++
title = "Seata 事务"
-weight = 5
+weight = 6
+++
## 启动 Seata 服务
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/seata.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/seata.en.md
index a0a2e80..d6b97e4 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/seata.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/usage/transaction/seata.en.md
@@ -1,6 +1,6 @@
+++
title = "Seata Transaction"
-weight = 5
+weight = 6
+++
## Startup Seata Server
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/configuration/props.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/configuration/props.cn.md
index 5dacb18..e9d8dd6 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/configuration/props.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/configuration/props.cn.md
@@ -23,3 +23,4 @@ Apache ShardingSphere 提供属性配置的方式配置系统级配置。
| proxy-transaction-type (?) | String | ShardingSphere-Proxy
中使用的默认事务类型。包括：LOCAL、XA 和 BASE。
| LOCAL
|
| proxy-opentracing-enabled (?) | boolean | 是否允许在
ShardingSphere-Proxy 中使用 OpenTracing。
| false |
| proxy-hint-enabled (?) | boolean | 是否允许在
ShardingSphere-Proxy 中使用 Hint。使用 Hint 会将 Proxy 的线程处理模型由 IO
多路复用变更为每个请求一个独立的线程，会降低 Proxy 的吞吐量。
| false |
+| transaction-manager-type (?) | String |
事务管理器类型。列如：atomikos，narayana。
| atomikos |
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/configuration/props.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/configuration/props.en.md
index 7ec75eb..f5190fb 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/configuration/props.en.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/configuration/props.en.md
@@ -23,3 +23,4 @@ Apache ShardingSphere provides the way of property
configuration to configure sy
| proxy-transaction-type (?) | String | Default transaction type
of ShardingSphere-Proxy. Include: LOCAL, XA and BASE.
| LOCAL
|
| proxy-opentracing-enabled (?) | boolean | Whether enable
opentracing for ShardingSphere-Proxy.
|
false |
| proxy-hint-enabled (?) | boolean | Whether enable hint for
ShardingSphere-Proxy. Using Hint will switch proxy thread mode from IO
multiplexing to per connection per thread, which will reduce system throughput.
|
false |
+| transaction-manager-type (?) | String | ShardingSphere
transaction manager type. Include: atomikos, narayana.
|
atomikos |
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/usage/transaction.cn.md
b/docs/document/content/user-manual/shardingsphere-proxy/usage/transaction.cn.md
index b1ef132..99accc5 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/usage/transaction.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/usage/transaction.cn.md
@@ -7,10 +7,53 @@ ShardingSphere-Proxy 接入的分布式事务 API 同 ShardingSphere-JDBC 保持
## XA 事务
-ShardingSphere-Proxy 原生支持 XA 事务，默认的事务管理器为 Atomikos。
+* ShardingSphere-Proxy 原生支持 XA 事务，默认的事务管理器为 Atomikos。
可以通过在 ShardingSphere-Proxy 的 conf 目录中添加 `jta.properties` 来定制化 Atomikos 配置项。
具体的配置规则请参考 Atomikos
的[官方文档](https://www.atomikos.com/Documentation/JtaProperties)。
+* 使用 Narayana事务管理器，需要参考以下步骤。
+
+步骤一：将 Narayana所需要的Jar包拷贝到 `/lib`。参考包如下：
+
+```xml
+<propeties>
+ <narayana.version>5.9.1.Final</narayana.version>
+
<jboss-transaction-spi.version>7.6.0.Final</jboss-transaction-spi.version>
+ <jboss-logging.version>3.2.1.Final</jboss-logging.version>
+</propeties>
+<dependency>
+ <groupId>org.jboss.narayana.jta</groupId>
+ <artifactId>jta</artifactId>
+ <version>${narayana.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.narayana.jts</groupId>
+ <artifactId>narayana-jts-integration</artifactId>
+ <version>${narayana.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jboss-transaction-spi</artifactId>
+ <version>${jboss-transaction-spi.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.logging</groupId>
+ <artifactId>jboss-logging</artifactId>
+ <version>${jboss-logging.version}</version>
+</dependency>
+```
+
+步骤二： 在`conf/server.yaml` 的属性配置中加入如下：
+
+```yaml
+props:
+ transaction-manager-type: narayana
+```
+
+步骤三： 新增 `jbossts-properties.xml`文件来定制化 Narayana 配置项，它的加载路径顺序：`user.dir (pwd)`
> `user.home` > `java.home` > `classpath`。
+详情请参见[Narayana官方文档](https://narayana.io/documentation/index.html)。
+
+
## BASE事务
BASE 目前没有集成至 ShardingSphere-Proxy 的二进制发布包中，使用时需要将实现了
`ShardingTransactionManager` SPI 的 jar 拷贝至 conf/lib 目录，然后切换事务类型为 BASE。
diff --git
a/docs/document/content/user-manual/shardingsphere-proxy/usage/transaction.en.md
b/docs/document/content/user-manual/shardingsphere-proxy/usage/transaction.en.md
index 64e3c06..ebdded5 100644
---
a/docs/document/content/user-manual/shardingsphere-proxy/usage/transaction.en.md
+++
b/docs/document/content/user-manual/shardingsphere-proxy/usage/transaction.en.md
@@ -9,6 +9,56 @@ ShardingSphere-Proxy supports LOCAL, XA, BASE transactions,
LOCAL transaction is
Default XA transaction manager of ShardingSphere is Atomikos. Users can
customize Atomikos configuration items through adding `jta.properties` in conf
catalog of ShardingSphere-Proxy. Please refer to [Official
Documents](https://www.atomikos.com/Documentation/JtaProperties) of Atomikos
for detailed configurations.
+* Use Narayana XA Transaction Manager。
+
+First：
+
+Copy the Jar package required by Narayana to '/lib'.The reference package is
as follows ：
+
+```xml
+<propeties>
+ <narayana.version>5.9.1.Final</narayana.version>
+
<jboss-transaction-spi.version>7.6.0.Final</jboss-transaction-spi.version>
+ <jboss-logging.version>3.2.1.Final</jboss-logging.version>
+</propeties>
+<dependency>
+ <groupId>org.jboss.narayana.jta</groupId>
+ <artifactId>jta</artifactId>
+ <version>${narayana.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.narayana.jts</groupId>
+ <artifactId>narayana-jts-integration</artifactId>
+ <version>${narayana.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss</groupId>
+ <artifactId>jboss-transaction-spi</artifactId>
+ <version>${jboss-transaction-spi.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.jboss.logging</groupId>
+ <artifactId>jboss-logging</artifactId>
+ <version>${jboss-logging.version}</version>
+</dependency>
+```
+
+Second：
+
+config `transaction-manager-type` in `conf/server.yaml`：
+
+```yaml
+props:
+ transaction-manager-type: narayana
+```
+
+Third：
+
+Developer can add `jbossts-properties.xml` of the application to customize
Narayana configuration.
+This is the point where the search path is applied - user.dir (pwd),
user.home, java.home, classpath.
+Please refer to [Narayana official
documentation](https://narayana.io/documentation/index.html) for more details.
+
+
## BASE Transaction
Since we have not packed the BASE implementation jar into
ShardingSphere-Proxy, you should copy relevant jar which implement
`ShardingTransactionManager` SPI to `conf/lib`, then switch the transaction
type to `BASE`.
