This is an automated email from the ASF dual-hosted git repository.
jianglongtao 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 4c137e436d3 Add a description of the Jakarta EE namespace in the
documentation for Spring Boot (#28303)
4c137e436d3 is described below
commit 4c137e436d30d526806182bb8cb098c6d24ef4b5
Author: Ling Hengqian <[email protected]>
AuthorDate: Wed Sep 13 10:55:27 2023 +0800
Add a description of the Jakarta EE namespace in the documentation for
Spring Boot (#28303)
---
.../jdbc-driver/spring-boot/_index.cn.md | 84 +++++++++++++++++++++
.../jdbc-driver/spring-boot/_index.en.md | 86 ++++++++++++++++++++++
2 files changed, 170 insertions(+)
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
index d820bf7349f..d3e5fd7e12c 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
@@ -34,3 +34,87 @@ spring.datasource.url=jdbc:shardingsphere:classpath:xxx.yaml
### 使用数据源
直接使用该数据源；或者将 ShardingSphereDataSource 配置在 JPA、Hibernate、MyBatis 等 ORM 框架中配合使用。
+
+## 针对 Spring Boot OSS 3 的特殊处理
+
+Spring Boot OSS 3 对 Jakarta EE 和 Java 17 进行了 “大爆炸” 升级，涉及大量复杂情况。
+
+对于正在使用 Java EE 8 API 及其实现的 ShardingSphere JDBC 而言，如果用户希望在 Spring Boot OSS 3
等基于 Jakarta EE 9+ API 的 Web
+Framework 上使用 ShardingSphere JDBC，则需要引入 Java EE 8 的 JAXB 的实现，并指定一个特定的
SnakeYAML 版本。
+
+这在 Maven 的 `pom.xml` 体现为如下内容。你也可以使用其他的 JAXB API 的实现。此配置同样适用于其他基于 Jakarta EE 的
Web Framework，如
+Quarkus 3，Micronaut Framework 4 和 Helidon 3。
+
+```xml
+<project>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.yaml</groupId>
+ <artifactId>snakeyaml</artifactId>
+ <version>1.33</version>
+ </dependency>
+ <dependency>
+ <groupId>org.glassfish.jaxb</groupId>
+ <artifactId>jaxb-runtime</artifactId>
+ <version>2.3.8</version>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+如果用户是通过 https://start.spring.io/ 创建了 Spring Boot 项目，或者在 `dependencyManagement`
的 XML 标签导入了
+`org.springframework.boot:spring-boot-dependencies` 的 POM 文件，则可通过如下内容来简化配置。
+
+```xml
+<project>
+ <properties>
+ <snakeyaml.version>1.33</snakeyaml.version>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.glassfish.jaxb</groupId>
+ <artifactId>jaxb-runtime</artifactId>
+ <version>2.3.8</version>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+此外，ShardingSphere 的 XA 分布式事务尚未在 Spring Boot OSS 3 上就绪。
+
+## 针对低版本的 Spring Boot OSS 2 的特殊处理
+
+ShardingSphere 的所有特性均可在 Spring Boot OSS 2 上使用，但低版本的 Spring Boot OSS 可能需要手动指定
SnakeYAML 的版本为 1.33 。
+这在 Maven 的 `pom.xml` 体现为如下内容。
+
+```xml
+<project>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.yaml</groupId>
+ <artifactId>snakeyaml</artifactId>
+ <version>1.33</version>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+如果用户是通过 https://start.spring.io/ 创建了 Spring Boot 项目，或者在 `dependencyManagement`
的 XML 标签导入了
+`org.springframework.boot:spring-boot-dependencies`的 POM 文件，同样可以选择通过配置
`snakeyaml.version` 的 `properties`
+来简化内容。
diff --git
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
index f605dcc5032..30c79616678 100644
---
a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
+++
b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
@@ -34,3 +34,89 @@ The YAML configuration file in 'spring.datasource.url'
currently support in thre
### Use Data Source
Use this data source directly; or configure ShardingSphereDataSource to be
used in conjunction with ORM frameworks such as JPA, Hibernate, and MyBatis.
+
+## Special handling for Spring Boot OSS 3
+
+Spring Boot OSS 3 has made a "big bang" upgrade to Jakarta EE and Java 17,
with all complications involved.
+
+For ShardingSphere JDBC that is using the Java EE 8 API and its
implementation, if you want to use ShardingSphere JDBC
+on a Jakarta EE 9+ API-based web framework such as Spring Boot OSS 3, you need
to introduce a JAXB implementation of
+Java EE 8 and specify a specific version of SnakeYAML.
+
+This is reflected in Maven's `pom.xml` as follows. You can also use other JAXB
API implementations. This configuration
+also applies to other Jakarta EE-based Web Frameworks, such as Quarkus 3,
Micronaut Framework 4 and Helidon 3.
+
+```xml
+<project>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.yaml</groupId>
+ <artifactId>snakeyaml</artifactId>
+ <version>1.33</version>
+ </dependency>
+ <dependency>
+ <groupId>org.glassfish.jaxb</groupId>
+ <artifactId>jaxb-runtime</artifactId>
+ <version>2.3.8</version>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+If the user created the Spring Boot project from https://start.spring.io/, or
the `dependencyManagement` XML tag was
+imported POM file for `org.springframework.boot:spring-boot-dependencies`,
users can simplify configuration by
+following things.
+
+```xml
+<project>
+ <properties>
+ <snakeyaml.version>1.33</snakeyaml.version>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.glassfish.jaxb</groupId>
+ <artifactId>jaxb-runtime</artifactId>
+ <version>2.3.8</version>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+In addition, ShardingSphere's XA distributed transactions are not yet ready on
Spring Boot OSS 3.
+
+## Special handling for earlier versions of Spring Boot OSS 2
+
+All features of ShardingSphere are available on Spring Boot OSS 2, but earlier
versions of Spring Boot OSS may require
+manually specifying version 1.33 for SnakeYAML.
+This is reflected in Maven's `pom.xml` as follows.
+
+```xml
+<project>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.shardingsphere</groupId>
+ <artifactId>shardingsphere-jdbc-core</artifactId>
+ <version>${shardingsphere.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.yaml</groupId>
+ <artifactId>snakeyaml</artifactId>
+ <version>1.33</version>
+ </dependency>
+ </dependencies>
+</project>
+```
+If the user created the Spring Boot project from https://start.spring.io/, or
the `dependencyManagement` XML tag was
+imported POM file for `org.springframework.boot:spring-boot-dependencies`,
users can also choose to simplify the content
+by configuring `properties` for `snakeyaml.version`.
