You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@shardingsphere.apache.org by zh...@apache.org on 2024/02/15 05:07:03 UTC

(shardingsphere) branch master updated: Updates Known Implementation documentation for ShardingSphere JDBC Driver (#30121)

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 c7e8e7d3618 Updates Known Implementation documentation for ShardingSphere JDBC Driver (#30121)
c7e8e7d3618 is described below

commit c7e8e7d3618d6da54076260b1b59aeb8a3e59828
Author: Ling Hengqian <li...@outlook.com>
AuthorDate: Thu Feb 15 13:06:57 2024 +0800

    Updates Known Implementation documentation for ShardingSphere JDBC Driver (#30121)
---
 .../jdbc-driver/known-implementation/_index.cn.md  | 162 +++++++++++++-----
 .../jdbc-driver/known-implementation/_index.en.md  | 185 +++++++++++++++------
 2 files changed, 251 insertions(+), 96 deletions(-)

diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.cn.md b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.cn.md
index c8221cbe950..c08ae9a288f 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.cn.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.cn.md
@@ -7,77 +7,143 @@ chapter = true
 ## 背景信息
 
 对于 `org.apache.shardingsphere.driver.ShardingSphereDriver` 的驱动类,
-通过实现 `org.apache.shardingsphere.driver.jdbc.core.driver.ShardingSphereURLProvider` 的 SPI,
+通过实现 `org.apache.shardingsphere.driver.jdbc.core.driver.url.ShardingSphereURLProvider` 的 SPI,
 可允许从多种来源和 File System 获取并解析为 ShardingSphere 的 YAML 配置文件。
+如无特定声明,以下实现均采用 YAML 1.1 作为 YAML 的编写规范,
+这并不阻止 `org.apache.shardingsphere.driver.jdbc.core.driver.url.ShardingSphereURLProvider` 的自定义实现从 XML 或 JSON 等文件手动转化为 YAML。
 
 在解析并加载 YAML 文件为 ShardingSphere 的元数据后,
-会再次通过[模式配置](../../../java-api/mode)的相关配置决定下一步行为。讨论两种情况:
+会再次通过[模式配置](../../../java-api/mode)的相关配置决定下一步行为。讨论两种情况,
+
 1. 元数据持久化仓库中不存在 ShardingSphere 的元数据,本地元数据将被存储到元数据持久化仓库。
 2. 元数据持久化仓库中已存在 ShardingSphere 的元数据,无论是否与本地元数据相同,本地元数据将被元数据持久化仓库的元数据覆盖。
 
 对元数据持久化仓库的配置需参考[元数据持久化仓库](../../../../common-config/builtin-algorithm/metadata-repository)。
 
-## URL 配置
+## 加载配置文件的方式
 
 ### 从类路径中加载配置文件
 
-加载类路径中 `config.yaml` 配置文件的 JDBC URL,通过 `jdbc:shardingsphere:classpath:` 前缀识别。
-配置文件为 `xxx.yaml`,配置文件格式与 [YAML 配置](../../../yaml-config)一致。
+配置文件为 `xxx.yaml`,当`placeholder-type`为`none`或不标明时,配置文件格式与 [YAML 配置](../../../yaml-config) 一致。
+当`placeholder-type`存在且不为`none`时,配置文件格式的定义参考本文的`JDBC URL 参数`一节。
 
 用例:
+
 - `jdbc:shardingsphere:classpath:config.yaml`
+- `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=none`
+- `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=environment`
+- `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=system_props`
 
 ### 从绝对路径中加载配置文件
 
-加载绝对路径中 `config.yaml` 配置文件的 JDBC URL,通过 `jdbc:shardingsphere:absolutepath:` 前缀识别。
-配置文件为 `xxx.yaml`,配置文件格式与 [YAML 配置](../../../yaml-config)一致。
+配置文件为 `xxx.yaml`,当`placeholder-type`为`none`或不标明时, 配置文件格式与 [YAML 配置](../../../yaml-config) 一致。
+当`placeholder-type`存在且不为`none`时,配置文件格式的定义参考本文的`JDBC URL 参数`一节。
 
 用例:
+
 - `jdbc:shardingsphere:absolutepath:/path/to/config.yaml`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=none`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=environment`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=system_props`
+
+## JDBC URL 参数
+
+对于 `org.apache.shardingsphere.driver.jdbc.core.driver.url.ShardingSphereURLProvider` 的实现,并非所有的 JDBC URL 参数都必须被解析,
+这涉及到如何实现 `org.apache.shardingsphere.driver.jdbc.core.driver.url.ShardingSphereURLProvider.getContent()`。
+
+### placeholder-type
+
+存在 `placeholder-type` 属性用于可选的加载包含动态占位符的配置文件,`placeholder-type` 存在默认值为`none`。
+当 `placeholder-type` 设置为非 `none` 时, 在涉及的 YAML 文件中允许通过动态占位符设置特定 YAML 属性的值,并配置可选的默认值。
+动态占位符的名称和其可选的默认值通过`::`分割, 在最外层通过`$${`和`}`包裹。
 
-### 加载包含环境变量的配置文件
+讨论两种情况,
 
-加载路径中包含环境变量的 `config.yaml` 配置文件的 JDBC URL,通过追加 `placeholder-type=xxx` 参数识别。
-`placeholder-type` 的取值范围包括 `none`(默认值), `environment` 和 `system_props`。
-配置文件为 `xxx.yaml`,配置文件格式与 [YAML 配置](../../../yaml-config)基本一致。
-在涉及的 YAML 文件中,允许通过环境变量设置特定 YAML 属性的值,并配置可选的默认值,这常用于 Docker 镜像的部署场景。
-环境变量的名称和其可选的默认值通过`::`分割,在最外层通过`$${`和`}`包裹。
+1. 当对应的动态占位符的值不存在时,此 YAML 属性的值将被设置为`::`右侧的默认值。
+2. 当对应的动态占位符的值和`::`右侧的默认值均不存在时,此属性将被设置为空。
 
-讨论两种情况。
-1. 当对应的环境变量不存在时,此 YAML 属性的值将被设置为`::`右侧的默认值。
-2. 当对应的环境变量和`::`右侧的默认值均不存在时,此属性将被设置为空。
+#### none
+
+配置文件为 `xxx.yaml`,配置文件格式与 [YAML 配置](../../../yaml-config) 一致。
+
+用例:
+
+- `jdbc:shardingsphere:classpath:config.yaml`
+- `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=none`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=none`
+
+#### environment
+
+加载包含环境变量的配置文件时,需将 `placeholder-type`置为`environment`,这常用于 Docker Image 的部署场景。
+配置文件为 `xxx.yaml`,配置文件格式与 [YAML 配置](../../../yaml-config) 基本一致。
 
 假设存在以下一组环境变量,
-1. 存在环境变量`FIXTURE_JDBC_URL`为`jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL`。
-2. 存在环境变量`FIXTURE_USERNAME`为`sa`。
 
-则对于以下 YAML 文件的截取片段:
+1. 存在环境变量 `FIXTURE_JDBC_URL` 为 `jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL`。
+2. 存在环境变量 `FIXTURE_USERNAME` 为 `sa`。
+
+则对于以下 YAML 文件的截取片段,
 
 ```yaml
 ds_1:
-    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
-    driverClassName: $${FIXTURE_DRIVER_CLASS_NAME::org.h2.Driver}
-    jdbcUrl: $${FIXTURE_JDBC_URL::jdbc:h2:mem:foo_ds_do_not_use}
-    username: $${FIXTURE_USERNAME::}
-    password: $${FIXTURE_PASSWORD::}
+  dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+  driverClassName: $${FIXTURE_DRIVER_CLASS_NAME::org.h2.Driver}
+  jdbcUrl: $${FIXTURE_JDBC_URL::jdbc:h2:mem:foo_ds_do_not_use}
+  username: $${FIXTURE_USERNAME::}
+  password: $${FIXTURE_PASSWORD::}
 ```
-此 YAML 截取片段将被解析为:
+
+此 YAML 截取片段将被解析为,
 
 ```yaml
 ds_1:
-    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
-    driverClassName: org.h2.Driver
-    jdbcUrl: jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL
-    username: sa
-    password:
+  dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+  driverClassName: org.h2.Driver
+  jdbcUrl: jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL
+  username: sa
+  password:
 ```
 
 用例:
+
 - `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=environment`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=environment`
+
+#### system_props
+
+加载包含系统属性的配置文件时,需将 `placeholder-type`置为`system_props`。
+配置文件为 `xxx.yaml`,配置文件格式与 [YAML 配置](../../../yaml-config) 基本一致。
+
+假设存在以下一组系统属性,
 
-在实际情况下,系统变量通常是动态定义的。
-假设如上系统变量均未定义,存在包含如上 YAML 截取片段的 YAML 文件 `config.yaml`,
-可参考如下方法创建 DataSource 实例。
+1. 存在系统属性 `fixture.config.driver.jdbc-url` 为 `jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL`。
+2. 存在系统属性 `fixture.config.driver.username` 为 `sa`。
+
+则对于以下 YAML 文件的截取片段,
+
+```yaml
+ds_1:
+  dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+  driverClassName: $${fixture.config.driver.driver-class-name::org.h2.Driver}
+  jdbcUrl: $${fixture.config.driver.jdbc-url::jdbc:h2:mem:foo_ds_do_not_use}
+  username: $${fixture.config.driver.username::}
+  password: $${fixture.config.driver.password::}
+```
+
+此 YAML 截取片段将被解析为,
+
+```yaml
+ds_1:
+  dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+  driverClassName: org.h2.Driver
+  jdbcUrl: jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL
+  username: sa
+  password:
+```
+
+在实际情况下,系统变量通常是动态定义的。假设如上系统变量均未定义,存在包含如上 YAML 截取片段的 YAML 文件 `config.yaml`,
+可参考如下方法,使用 HikariCP Java API 创建 DataSource 实例。
 
 ```java
 import com.zaxxer.hikari.HikariConfig;
@@ -85,25 +151,29 @@ import com.zaxxer.hikari.HikariDataSource;
 
 import javax.sql.DataSource;
 
-public DataSource createDataSource() {
-    HikariConfig config = new HikariConfig();
-    config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
-    config.setJdbcUrl("jdbc:shardingsphere:classpath:config.yaml?placeholder-type=system_props");
-    try {
-        assert null == System.getProperty("fixture.config.driver.jdbc-url");
-        assert null == System.getProperty("fixture.config.driver.username");
-        System.setProperty("fixture.config.driver.jdbc-url", "jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL");
-        System.setProperty("fixture.config.driver.username", "sa");
-        return new HikariDataSource(config);
-    } finally {
-        System.clearProperty("fixture.config.driver.jdbc-url");
-        System.clearProperty("fixture.config.driver.username");
+public class ExampleUtils {
+    public DataSource createDataSource() {
+        HikariConfig config = new HikariConfig();
+        config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
+        config.setJdbcUrl("jdbc:shardingsphere:classpath:config.yaml?placeholder-type=system_props");
+        try {
+            assert null == System.getProperty("fixture.config.driver.jdbc-url");
+            assert null == System.getProperty("fixture.config.driver.username");
+            System.setProperty("fixture.config.driver.jdbc-url", "jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL");
+            System.setProperty("fixture.config.driver.username", "sa");
+            return new HikariDataSource(config);
+        } finally {
+            System.clearProperty("fixture.config.driver.jdbc-url");
+            System.clearProperty("fixture.config.driver.username");
+        }
     }
 }
 ```
 
 用例:
+
 - `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=system_props`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=system_props`
 
 ### 其他实现
 
diff --git a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.en.md b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.en.md
index 263bf729dfc..00d7787fed3 100644
--- a/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.en.md
+++ b/docs/document/content/user-manual/shardingsphere-jdbc/yaml-config/jdbc-driver/known-implementation/_index.en.md
@@ -7,49 +7,95 @@ chapter = true
 ## Background Information
 
 For the driver class of `org.apache.shardingsphere.driver.ShardingSphereDriver`,
-by implementing the SPI of `org.apache.shardingsphere.driver.jdbc.core.driver.ShardingSphereURLProvider`,
+by implementing the SPI of `org.apache.shardingsphere.driver.jdbc.core.driver.url.ShardingSphereURLProvider`,
 allows YAML configuration files to be fetched from multiple sources and File Systems and parsed into ShardingSphere.
+If there is no specific statement, the following implementations all use YAML 1.1 as the YAML writing specification.
+This does not prevent custom implementations of `org.apache.shardingsphere.driver.jdbc.core.driver.url.ShardingSphereURLProvider` from being manually converted to YAML from files such as XML or JSON.
 
-After parsing and loading the YAML file into ShardingSphere's metadata,
-The next behavior will be determined again through the relevant configuration of [Mode Configuration](../../../java-api/mode). Discuss two situations:
-1. ShardingSphere’s metadata does not exist in the metadata repository, and local metadata will be stored in the metadata repository.
-2. ShardingSphere’s metadata already exists in the metadata repository, regardless of whether it is the same as the local metadata, 
-the local metadata will be overwritten by the metadata of the metadata repository.
+After parsing and loading the YAML file into ShardingSphere's metadata, 
+the next behavior will be determined again through the relevant configuration of [Mode Configuration](../../../java-api/mode). 
+Discuss two situations,
 
-For the configuration of the metadata repository, please refer to [Metadata Repository](../../../../common-config/builtin-algorithm/metadata-repository).
+1. ShardingSphere’s metadata does not exist in the Metadata Repository, and local metadata will be stored in the Metadata Repository.
+2. The metadata of ShardingSphere already exists in the Metadata Repository. 
+   Regardless of whether it is the same as the local metadata, 
+   the local metadata will be overwritten by the metadata of the Metadata Repository.
 
-## URL configuration
+For the configuration of the Metadata Repository, 
+please refer to [Metadata Repository](../../../../common-config/builtin-algorithm/metadata-repository).
+
+## How to load configuration files
 
 ### Load configuration files from classpath
 
-Load the JDBC URL of the `config.yaml` configuration file in classpath, identified by the `jdbc:shardingsphere:classpath:` prefix.
-The configuration file is `xxx.yaml`, and the configuration file format is consistent with [YAML configuration](../../../yaml-config).
+The configuration file is `xxx.yaml`. When `placeholder-type` is `none` or is not specified, 
+the configuration file format is consistent with [YAML configuration](../../../yaml-config).
+When `placeholder-type` exists and is not `none`, 
+the configuration file format is defined in the `JDBC URL Parameters` section of this article.
 
 Example:
+
 - `jdbc:shardingsphere:classpath:config.yaml`
+- `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=none`
+- `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=environment`
+- `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=system_props`
 
 ### Load configuration file from absolute path
 
-JDBC URL to load the `config.yaml` configuration file in an absolute path, identified by the `jdbc:shardingsphere:absolutepath:` prefix.
-The configuration file is `xxx.yaml`, and the configuration file format is consistent with [YAML configuration](../../../yaml-config).
+The configuration file is `xxx.yaml`. When `placeholder-type` is `none` or is not specified, 
+the configuration file format is consistent with [YAML configuration](../../../yaml-config).
+When `placeholder-type` exists and is not `none`, 
+the configuration file format is defined in the `JDBC URL Parameters`section of this article.
 
 Example:
+
 - `jdbc:shardingsphere:absolutepath:/path/to/config.yaml`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=none`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=environment`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=system_props`
 
-### Load configuration file containing environment variables
+## JDBC URL parameters
 
-Loading the JDBC URL from the `config.yaml` configuration file whose path contains environment variables, and appending the `placeholder-type=xxx` parameter to identify it.
-The value range of `placeholder-type` includes `none` (default value), `environment`, and `system_props`.
-The configuration file is `xxx.yaml`, and the configuration file format is basically the same as [YAML configuration](../../../yaml-config).
-Allows setting the value of specific YAML properties via environment variables and configuring optional default values in the involved YAML files. 
-This is commonly used in Docker Image deployment scenarios.
-The name of an environment variable and its optional default value are separated by `::` and wrapped in the outermost layer by `$${` and `}`.
+For implementations of `org.apache.shardingsphere.driver.jdbc.core.driver.url.ShardingSphereURLProvider`, 
+not all JDBC URL parameters must be parsed,
+this involves how to implement `org.apache.shardingsphere.driver.jdbc.core.driver.url.ShardingSphereURLProvider.getContent()`.
+
+### placeholder-type
+
+There is a `placeholder-type` attribute for optional loading of configuration files containing dynamic placeholders. 
+The default value of `placeholder-type` is `none`.
+When `placeholder-type` is set to something other than `none`, allows setting the value of specific YAML properties via
+dynamic placeholders in the involved YAML file, and configuring optional default values.
+The name of a dynamic placeholder and its optional default value are separated by `::` and wrapped in the outermost
+layer by `$${` and `}`.
+
+Discuss two situations,
+
+1. When the corresponding dynamic placeholder value does not exist, 
+   the value of this YAML attribute will be set to the default value on the right side of `::`.
+2. When neither the corresponding dynamic placeholder value nor the default value on the right side of `::` exists, 
+   this attribute will be set to empty.
 
-Discuss two situations.
-1. When the corresponding environment variable does not exist, the value of this YAML attribute will be set to the default value on the right side of `::`.
-2. When the corresponding environment variable and the default value on the right side of `::` do not exist, this property will be set to empty.
+#### none
+
+The configuration file is `xxx.yaml`, and the configuration file format is consistent
+with [YAML configuration](../../../yaml-config).
+
+Example:
+
+- `jdbc:shardingsphere:classpath:config.yaml`
+- `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=none`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=none`
+
+#### environment
+
+When loading a configuration file containing environment variables,
+users need to set `placeholder-type` to `environment`, which is commonly used in Docker Image deployment scenarios.
+The configuration file is `xxx.yaml`, and the configuration file format is basically the same as [YAML configuration](../../../yaml-config).
 
 Assume that the following set of environment variables exists,
+
 1. The existing environment variable `FIXTURE_JDBC_URL` is `jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL`.
 2. The existing environment variable `FIXTURE_USERNAME` is `sa`.
 
@@ -57,30 +103,65 @@ Then for the intercepted fragment of the following YAML file,
 
 ```yaml
 ds_1:
-    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
-    driverClassName: $${FIXTURE_DRIVER_CLASS_NAME::org.h2.Driver}
-    jdbcUrl: $${FIXTURE_JDBC_URL::jdbc:h2:mem:foo_ds_do_not_use}
-    username: $${FIXTURE_USERNAME::}
-    password: $${FIXTURE_PASSWORD::}
+  dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+  driverClassName: $${FIXTURE_DRIVER_CLASS_NAME::org.h2.Driver}
+  jdbcUrl: $${FIXTURE_JDBC_URL::jdbc:h2:mem:foo_ds_do_not_use}
+  username: $${FIXTURE_USERNAME::}
+  password: $${FIXTURE_PASSWORD::}
 ```
-This YAML snippet will be parsed as:
+
+This YAML snippet will be parsed as,
 
 ```yaml
 ds_1:
-    dataSourceClassName: com.zaxxer.hikari.HikariDataSource
-    driverClassName: org.h2.Driver
-    jdbcUrl: jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL
-    username: sa
-    password:
+  dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+  driverClassName: org.h2.Driver
+  jdbcUrl: jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL
+  username: sa
+  password:
 ```
 
 Example:
+
 - `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=environment`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=environment`
+
+#### system_props
+
+When loading a configuration file containing system properties, users need to set `placeholder-type` to `system_props`.
+The configuration file is `xxx.yaml`, and the configuration file format is basically the same as [YAML configuration](../../../yaml-config).
 
-In real situations, system variables are usually defined dynamically.
-Assume that none of the above system variables are defined, 
+Assume the following set of system properties exists,
+
+1. The existing system property `fixture.config.driver.jdbc-url` is `jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL`.
+2. The existing system property `fixture.config.driver.username` is `sa`.
+
+Then for the intercepted fragment of the following YAML file,
+
+```yaml
+ds_1:
+  dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+  driverClassName: $${fixture.config.driver.driver-class-name::org.h2.Driver}
+  jdbcUrl: $${fixture.config.driver.jdbc-url::jdbc:h2:mem:foo_ds_do_not_use}
+  username: $${fixture.config.driver.username::}
+  password: $${fixture.config.driver.password::}
+```
+
+This YAML snippet will be parsed as,
+
+```yaml
+ds_1:
+  dataSourceClassName: com.zaxxer.hikari.HikariDataSource
+  driverClassName: org.h2.Driver
+  jdbcUrl: jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL
+  username: sa
+  password:
+```
+
+In real situations, system variables are usually defined dynamically. 
+Assume that none of the above system variables are defined,
 and there is a YAML file `config.yaml` containing the above YAML interception fragment,
-Users can refer to the following methods to create a DataSource instance.
+users can refer to the following method to create a DataSource instance using the HikariCP Java API.
 
 ```java
 import com.zaxxer.hikari.HikariConfig;
@@ -88,26 +169,30 @@ import com.zaxxer.hikari.HikariDataSource;
 
 import javax.sql.DataSource;
 
-public DataSource createDataSource() {
-    HikariConfig config = new HikariConfig();
-    config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
-    config.setJdbcUrl("jdbc:shardingsphere:classpath:config.yaml?placeholder-type=system_props");
-    try {
-        assert null == System.getProperty("fixture.config.driver.jdbc-url");
-        assert null == System.getProperty("fixture.config.driver.username");
-        System.setProperty("fixture.config.driver.jdbc-url", "jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL");
-        System.setProperty("fixture.config.driver.username", "sa");
-        return new HikariDataSource(config);
-    } finally {
-        System.clearProperty("fixture.config.driver.jdbc-url");
-        System.clearProperty("fixture.config.driver.username");
+public class ExampleUtils {
+    public DataSource createDataSource() {
+        HikariConfig config = new HikariConfig();
+        config.setDriverClassName("org.apache.shardingsphere.driver.ShardingSphereDriver");
+        config.setJdbcUrl("jdbc:shardingsphere:classpath:config.yaml?placeholder-type=system_props");
+        try {
+            assert null == System.getProperty("fixture.config.driver.jdbc-url");
+            assert null == System.getProperty("fixture.config.driver.username");
+            System.setProperty("fixture.config.driver.jdbc-url", "jdbc:h2:mem:foo_ds_1;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=false;MODE=MySQL");
+            System.setProperty("fixture.config.driver.username", "sa");
+            return new HikariDataSource(config);
+        } finally {
+            System.clearProperty("fixture.config.driver.jdbc-url");
+            System.clearProperty("fixture.config.driver.username");
+        }
     }
 }
 ```
 
 Example:
+
 - `jdbc:shardingsphere:classpath:config.yaml?placeholder-type=system_props`
+- `jdbc:shardingsphere:absolutepath:/path/to/config.yaml?placeholder-type=system_props`
 
 ### Other implementations
 
-For details, please refer to https://github.com/apache/shardingsphere-plugin .
+For details, please refer to https://github.com/apache/shardingsphere-plugin.