Skip to content

Commit

Permalink
Add a description of the Jakarta EE namespace in the documentation fo…
Browse files Browse the repository at this point in the history 
…r Spring Boot (#28303)
  • Loading branch information
@linghengqian
linghengqian authored Sep 13, 2023
1 parent 05d5a9b commit 4c137e4
Show file tree
Hide file tree
Showing 2 changed files with 170 additions and 0 deletions.
84 changes: 84 additions & 0 deletions ...ser-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.cn.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`
来简化内容。
86 changes: 86 additions & 0 deletions ...ser-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/spring-boot/_index.en.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

0 comments on commit 4c137e4

Please sign in to comment.