From 4c137e436d30d526806182bb8cb098c6d24ef4b5 Mon Sep 17 00:00:00 2001 From: Ling Hengqian Date: Wed, 13 Sep 2023 10:55:27 +0800 Subject: [PATCH] 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 d820bf7349f44..d3e5fd7e12cb2 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 + + + + org.apache.shardingsphere + shardingsphere-jdbc-core + ${shardingsphere.version} + + + org.yaml + snakeyaml + 1.33 + + + org.glassfish.jaxb + jaxb-runtime + 2.3.8 + + + +``` + +如果用户是通过 https://start.spring.io/ 创建了 Spring Boot 项目，或者在 `dependencyManagement` 的 XML 标签导入了 +`org.springframework.boot:spring-boot-dependencies` 的 POM 文件，则可通过如下内容来简化配置。 + +```xml + + + 1.33 + + + + + org.apache.shardingsphere + shardingsphere-jdbc-core + ${shardingsphere.version} + + + org.glassfish.jaxb + jaxb-runtime + 2.3.8 + + + +``` + +此外，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 + + + + org.apache.shardingsphere + shardingsphere-jdbc-core + ${shardingsphere.version} + + + org.yaml + snakeyaml + 1.33 + + + +``` + +如果用户是通过 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 f605dcc5032f5..30c796166788e 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 + + + + org.apache.shardingsphere + shardingsphere-jdbc-core + ${shardingsphere.version} + + + org.yaml + snakeyaml + 1.33 + + + org.glassfish.jaxb + jaxb-runtime + 2.3.8 + + + +``` + +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 + + + 1.33 + + + + + org.apache.shardingsphere + shardingsphere-jdbc-core + ${shardingsphere.version} + + + org.glassfish.jaxb + jaxb-runtime + 2.3.8 + + + +``` + +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 + + + + org.apache.shardingsphere + shardingsphere-jdbc-core + ${shardingsphere.version} + + + org.yaml + snakeyaml + 1.33 + + + +``` +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`.