Add Interval implementation of InlineExpressionParser SPI (#29309)

apache · Dec 12, 2023 · 440064a · 440064a
1 parent 5f7d21e
commit 440064a
Show file tree

Hide file tree

Showing 10 changed files with 493 additions and 2 deletions.
diff --git a/docs/document/content/dev-manual/sharding.cn.md b/docs/document/content/dev-manual/sharding.cn.md
@@ -96,4 +96,5 @@ chapter = true
 |----------|----------------------------------------------------|--------------------------------------------------------------------------------|
 | GROOVY   | 使用 Groovy 语法的行表达式                                  | `org.apache.shardingsphere.infra.expr.groovy.GroovyInlineExpressionParser`     |
 | LITERAL  | 使用标准列表的行表达式                                        | `org.apache.shardingsphere.infra.expr.literal.LiteralInlineExpressionParser`   |
+| INTERVAL | 基于固定时间范围的 Key-Value 语法的行表达式                        | `org.apache.shardingsphere.infra.expr.interval.IntervalInlineExpressionParser` |
 | ESPRESSO | 基于 GraalVM Truffle 的 Espresso 实现的使用 Groovy 语法的行表达式 | `org.apache.shardingsphere.infra.expr.espresso.EspressoInlineExpressionParser` |
diff --git a/docs/document/content/dev-manual/sharding.en.md b/docs/document/content/dev-manual/sharding.en.md
@@ -96,4 +96,5 @@ Row Value Expressions definition
 |----------------------|------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------|
 | GROOVY               | Row Value Expressions that uses the Groovy syntax                                                    | `org.apache.shardingsphere.infra.expr.groovy.GroovyInlineExpressionParser`     |
 | LITERAL              | Row Value Expressions that uses a standard list                                                      | `org.apache.shardingsphere.infra.expr.literal.LiteralInlineExpressionParser`   |
+| INTERVAL             | Row Value Expressions based on fixed interval that uses the Key-Value syntax                         | `org.apache.shardingsphere.infra.expr.interval.IntervalInlineExpressionParser` |                                                                             |
 | ESPRESSO             | Row Value Expressions that uses the Groovy syntax based on GraalVM Truffle's Espresso implementation | `org.apache.shardingsphere.infra.expr.espresso.EspressoInlineExpressionParser` |
diff --git a/docs/document/content/user-manual/common-config/builtin-algorithm/expr.cn.md b/docs/document/content/user-manual/common-config/builtin-algorithm/expr.cn.md
@@ -27,9 +27,46 @@ weight = 10
 - `<LITERAL>t_order_1, t_order_2, t_order_3` 将被转化为 `t_order_1, t_order_2, t_order_3`
 - `<LITERAL>t_order_${1..3}` 将被转化为 `t_order_${1..3}`
 
+## 基于固定时间范围的 Key-Value 语法的行表达式
+
+`INTERVAL` 实现引入了 Key-Value 风格的属性语法，来通过单行字符串定义一组时间范围内的字符串。这通常用于简化对 `数据分片` 功能的 `actualDataNodes` 的定义。
+
+`INTERVAL` 实现定义多个属性的方式为 `Key1=Value1;Key2=Value2`，通过 `;` 号分割键值对，通过 `=` 号分割 `Key` 值和 `Value` 值。
+
+此实现主动忽视了 `SP` 的时区信息，这意味着当 `DL` 和 `DU` 含有时区信息时，不会因为时区不一致而发生时区转换。
+
+此实现键值对的顺序不敏感， 行表达式尾部不携带 `;` 号。
+
+`INTERVAL` 实现引入了如下 Key 的键值：
+
+1. `P` 代表 prefix 的缩写，意为结果列表单元的前缀, 通常代表真实表的前缀格式。
+2. `SP` 代表 suffix pattern 的缩写，意为结果列表单元的后缀的时间戳格式, 通常代表真实表的后缀格式，必须遵循 Java DateTimeFormatter 的格式。
+例如：yyyyMMdd，yyyyMM 或 yyyy 等。
+3. `DIA` 代表 datetime interval amount 的缩写，意为结果列表单元的时间间隔。
+4. `DIU` 代表 datetime interval unit 的缩写，意为分片键时间间隔单位，必须遵循 Java `java.time.temporal.ChronoUnit#toString()` 的枚举值。例如：`Months`。
+5. `DL` 代表 datetime lower 的缩写，意为时间下界值，格式与 `SP` 定义的时间戳格式一致。
+6. `DU` 代表 datetime upper 的缩写，意为时间上界值，格式与 `SP` 定义的时间戳格式一致。
+7. `C` 代表 chronology 的缩写，意为日历系统，必须遵循 Java `java.time.chrono.Chronology#getId()` 的格式。
+例如：`Japanese`，`Minguo`，`ThaiBuddhist`。存在默认值为 `ISO`。
+受 https://bugs.openjdk.org/browse/JDK-8068571 影响，`Japanese` 仅在 JDK 11+ 上可用。
+
+类型：INTERVAL
+
+用例：
+
+- `<INTERVAL>P=t_order_;SP=yyyy_MMdd;DIA=1;DIU=Days;DL=2023_1202;DU=2023_1204` 将被转化为 `t_order_2023_1202, t_order_2023_1203, t_order_2023_1204`
+- `<INTERVAL>P=t_order_;SP=yyyy_MM;DIA=1;DIU=Months;DL=2023_10;DU=2023_12` 将被转化为 `t_order_2023_10, t_order_2023_11, t_order_2023_12`
+- `<INTERVAL>P=t_order_;SP=yyyy;DIA=1;DIU=Years;DL=2021;DU=2023` 将被转化为 `t_order_2021, t_order_2022, t_order_2023`
+- `<INTERVAL>P=t_order_;SP=HH_mm_ss_SSS;DIA=1;DIU=Millis;DL=22_48_52_131;DU=22_48_52_133` 将被转化为 `t_order_22_48_52_131, t_order_22_48_52_132, t_order_22_48_52_133`
+- `<INTERVAL>P=t_order_;SP=yyyy_MM_dd_HH_mm_ss_SSS;DIA=1;DIU=Days;DL=2023_12_04_22_48_52_131;DU=2023_12_06_22_48_52_131` 将被转化为 `t_order_2023_12_04_22_48_52_131, t_order_2023_12_05_22_48_52_131, t_order_2023_12_06_22_48_52_131`
+- `<INTERVAL>P=t_order_;SP=MM;DIA=1;DIU=Months;DL=10;DU=12` 将被转化为 `t_order_10, t_order_11, t_order_12`
+- `<INTERVAL>P=t_order_;SP=GGGGyyyy_MM_dd;DIA=1;DIU=Days;DL=平成0001_12_05;DU=平成0001_12_06;C=Japanese` 将被转化为 `t_order_平成0001_12_05, t_order_平成0001_12_06`
+- `<INTERVAL>P=t_order_;SP=GGGGyyy_MM_dd;DIA=1;DIU=Days;DL=平成001_12_05;DU=平成001_12_06;C=Japanese` 将被转化为 `t_order_平成001_12_05, t_order_平成001_12_06`
+- `<INTERVAL>P=t_order_;SP=GGGGy_MM_dd;DIA=1;DIU=Days;DL=平成1_12_05;DU=平成1_12_06;C=Japanese` 将被转化为 `t_order_平成1_12_05, t_order_平成1_12_06`
+
 ## 基于 GraalVM Truffle 的 Espresso 实现的使用 Groovy 语法的行表达式
 
-此为可选实现，你需要在自有项目的 `pom.xml` 主动声明如下依赖。并且请确保自有项目通过 GraalVM CE 23.0.1 For JDK17 编译。
+此为可选实现，你需要在自有项目的 `pom.xml` 主动声明如下依赖。并且请确保自有项目通过 GraalVM CE 23.0.1 For JDK 17.0.9 编译。
 
 ```xml
 <dependencies>

diff --git a/docs/document/content/user-manual/common-config/builtin-algorithm/expr.en.md b/docs/document/content/user-manual/common-config/builtin-algorithm/expr.en.md
@@ -31,10 +31,51 @@ Example:
 - `<LITERAL>t_order_1, t_order_2, t_order_3` will be converted to `t_order_1, t_order_2, t_order_3`
 - `<LITERAL>t_order_${1..3}` will be converted to `t_order_${1..3}`
 
+## Row Value Expressions based on fixed interval that uses the Key-Value syntax
+
+The `INTERVAL` implementation introduces a Key-Value style property syntax to define a set of time ranges of strings via a single line string. 
+This is often used to simplify the definition of `actualDataNodes` for `Sharding` feature.
+
+`INTERVAL` implements the method of defining multiple attributes as `Key1=Value1;Key2=Value2`, using `;` to separate key-value pairs, and `=` to separate `Key` values and `Value` values.
+
+This implementation actively ignores the time zone information of `SP`, which means that when `DL` and `DU` contain time zone information, 
+no time zone conversion will occur due to inconsistent time zones. 
+
+This implementation is not sensitive to the order of key-value pairs, and the line expression does not carry the `;` sign at the end.
+
+The `INTERVAL` implementation introduces the following Key values:
+
+1. `P` stands for the abbreviation of prefix, which means the prefix of the result list unit, usually representing the prefix format of the real table.
+2. `SP` stands for the abbreviation of suffix pattern, which means the timestamp format of the suffix of the result list unit. 
+It usually represents the suffix format of the real table and must follow the format of Java DateTimeFormatter. 
+For example: yyyyMMdd, yyyyMM or yyyy etc.
+3. `DIA` stands for the abbreviation of datetime interval amount, which means the time interval of the result list unit.
+4. `DIU` stands for the abbreviation of datetime interval unit, which means the shard key time interval unit. 
+It must follow the enumeration value of Java `java.time.temporal.ChronoUnit#toString()`. For example: `Months`.
+5. `DL` stands for the abbreviation of datetime lower, which means the lower bound of time. The format is consistent with the timestamp format defined by `SP`.
+6. `DU` stands for the abbreviation of datetime upper, which means the upper bound value of time. The format is consistent with the timestamp format defined by `SP`.
+7. `C` stands for the abbreviation of chronology, which means calendar system and must follow the format of Java `java.time.chrono.Chronology#getId()`.
+For example: `Japanese`, `Minguo`, `ThaiBuddhist`. There is a default value of `ISO`.
+Affected by https://bugs.openjdk.org/browse/JDK-8068571, `Japanese` is only available on JDK 11+.
+
+Type: INTERVAL
+
+Example:
+
+- `<INTERVAL>P=t_order_;SP=yyyy_MMdd;DIA=1;DIU=Days;DL=2023_1202;DU=2023_1204` will be converted to `t_order_2023_1202, t_order_2023_1203, t_order_2023_1204`
+- `<INTERVAL>P=t_order_;SP=yyyy_MM;DIA=1;DIU=Months;DL=2023_10;DU=2023_12` will be converted to `t_order_2023_10, t_order_2023_11, t_order_2023_12`
+- `<INTERVAL>P=t_order_;SP=yyyy;DIA=1;DIU=Years;DL=2021;DU=2023` will be converted to `t_order_2021, t_order_2022, t_order_2023`
+- `<INTERVAL>P=t_order_;SP=HH_mm_ss_SSS;DIA=1;DIU=Millis;DL=22_48_52_131;DU=22_48_52_133` will be converted to `t_order_22_48_52_131, t_order_22_48_52_132, t_order_22_48_52_133`
+- `<INTERVAL>P=t_order_;SP=yyyy_MM_dd_HH_mm_ss_SSS;DIA=1;DIU=Days;DL=2023_12_04_22_48_52_131;DU=2023_12_06_22_48_52_131` will be converted to `t_order_2023_12_04_22_48_52_131, t_order_2023_12_05_22_48_52_131, t_order_2023_12_06_22_48_52_131`
+- `<INTERVAL>P=t_order_;SP=MM;DIA=1;DIU=Months;DL=10;DU=12` will be converted to `t_order_10, t_order_11, t_order_12`
+- `<INTERVAL>P=t_order_;SP=GGGGyyyy_MM_dd;DIA=1;DIU=Days;DL=平成0001_12_05;DU=平成0001_12_06;C=Japanese` will be converted to `t_order_平成0001_12_05, t_order_平成0001_12_06`
+- `<INTERVAL>P=t_order_;SP=GGGGyyy_MM_dd;DIA=1;DIU=Days;DL=平成001_12_05;DU=平成001_12_06;C=Japanese` will be converted to `t_order_平成001_12_05, t_order_平成001_12_06`
+- `<INTERVAL>P=t_order_;SP=GGGGy_MM_dd;DIA=1;DIU=Days;DL=平成1_12_05;DU=平成1_12_06;C=Japanese` will be converted to `t_order_平成1_12_05, t_order_平成1_12_06`
+
 ## Row Value Expressions that uses the Groovy syntax based on GraalVM Truffle's Espresso implementation
 
 This is an optional implementation, and you need to actively declare the following dependencies in the `pom.xml` of your own project.
-And make sure your own project is compiled with GraalVM CE 23.0.1 For JDK17.
+And make sure your own project is compiled with GraalVM CE 23.0.1 For JDK 17.0.9.
 
 ```xml
 <dependencies>

diff --git a/infra/expr/core/pom.xml b/infra/expr/core/pom.xml
@@ -42,6 +42,11 @@
             <artifactId>shardingsphere-infra-expr-literal</artifactId>
             <version>${project.version}</version>
         </dependency>
+        <dependency>
+            <groupId>org.apache.shardingsphere</groupId>
+            <artifactId>shardingsphere-infra-expr-interval</artifactId>
+            <version>${project.version}</version>
+        </dependency>
 
         <dependency>
             <groupId>org.apache.shardingsphere</groupId>

diff --git a/infra/expr/type/interval/pom.xml b/infra/expr/type/interval/pom.xml
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one or more
+  ~ contributor license agreements.  See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright ownership.
+  ~ The ASF licenses this file to You under the Apache License, Version 2.0
+  ~ (the "License"); you may not use this file except in compliance with
+  ~ the License.  You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.apache.shardingsphere</groupId>
+        <artifactId>shardingsphere-infra-expr-type</artifactId>
+        <version>5.4.2-SNAPSHOT</version>
+    </parent>
+    <artifactId>shardingsphere-infra-expr-interval</artifactId>
+    <name>${project.artifactId}</name>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.shardingsphere</groupId>
+            <artifactId>shardingsphere-infra-expr-spi</artifactId>
+            <version>${project.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.apache.shardingsphere</groupId>
+            <artifactId>shardingsphere-test-util</artifactId>
+            <version>${project.version}</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>