You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by ja...@apache.org on 2022/09/19 14:16:13 UTC
[flink] 02/02: [FLINK-29023][docs][table] Improve docs of limitation of ADD JAR
This is an automated email from the ASF dual-hosted git repository.
jark pushed a commit to branch release-1.16
in repository https://gitbox.apache.org/repos/asf/flink.git
commit d18fc95cfd3ba7e5aa91810380de65198cfea9d8
Author: Jark Wu <ja...@apache.org>
AuthorDate: Mon Sep 19 17:40:27 2022 +0800
[FLINK-29023][docs][table] Improve docs of limitation of ADD JAR
---
docs/content.zh/docs/dev/table/catalogs.md | 4 +++-
docs/content.zh/docs/dev/table/sourcesSinks.md | 4 +++-
docs/content.zh/docs/dev/table/sql/jar.md | 5 +++--
docs/content/docs/dev/table/catalogs.md | 4 +++-
docs/content/docs/dev/table/sourcesSinks.md | 4 +++-
docs/content/docs/dev/table/sql/jar.md | 2 +-
6 files changed, 16 insertions(+), 7 deletions(-)
diff --git a/docs/content.zh/docs/dev/table/catalogs.md b/docs/content.zh/docs/dev/table/catalogs.md
index 9f1a00b5e75..89ba02c0572 100644
--- a/docs/content.zh/docs/dev/table/catalogs.md
+++ b/docs/content.zh/docs/dev/table/catalogs.md
@@ -61,7 +61,9 @@ Catalog 是可扩展的，用户可以通过实现 `Catalog` 接口来开发自
`CatalogFactory` 定义了一组属性，用于 SQL CLI 启动时配置 Catalog。
这组属性集将传递给发现服务，在该服务中，服务会尝试将属性关联到 `CatalogFactory` 并初始化相应的 Catalog 实例。
-注意：从 FLINK-15635 开始，table 模块引入了一个用户类加载器，以统一管理所有的用户 jar 包，例如通过 `ADD JAR` 语句添加的 jar。在自定义 Catalog 中，如果需要明确加载某些类，请使用用户类加载器而不是线程上下文类加载器，否则可能会出现 ClassNotFoundException 异常。用户可以通过 `CatalogFactory.Context` 获得用户类加载器。
+{{< hint warning >}}从 Flink v1.16 开始, TableEnvironment 引入了一个用户类加载器，以在 table 程序、SQL Client、SQL Gateway 中保持一致的类加载行为。该类加载器会统一管理所有的用户 jar 包，包括通过 `ADD JAR` 或 `CREATE FUNCTION .. USING JAR ..` 添加的 jar 资源。
+ 在用户自定义 catalog 中，应该将 `Thread.currentThread().getContextClassLoader()` 替换成该用户类加载器去加载类。否则，可能会发生 `ClassNotFoundException` 的异常。该用户类加载器可以通过 `CatalogFactory.Context#getClassLoader` 获得。
+{{< /hint >}}
## 如何创建 Flink 表并将其注册到 Catalog
diff --git a/docs/content.zh/docs/dev/table/sourcesSinks.md b/docs/content.zh/docs/dev/table/sourcesSinks.md
index 0150d3e6b30..90d0adc1437 100644
--- a/docs/content.zh/docs/dev/table/sourcesSinks.md
+++ b/docs/content.zh/docs/dev/table/sourcesSinks.md
@@ -40,7 +40,9 @@ for more information about built-in table sources and sinks.
This page focuses on how to develop a custom, user-defined connector.
-注意：从 FLINK-15635 开始，table 模块引入了一个用户类加载器，以统一管理所有的用户 jar 包，例如通过 `ADD JAR` 语句添加的 jar。在用户自定义连接器中，如果需要明确加载某些类，请使用用户类加载器而不是线程上下文类加载器，否则可能会出现 ClassNotFoundException 异常。用户可以通过 `DynamicTableFactory.Context` 获得用户类加载器。
+{{< hint warning >}}从 Flink v1.16 开始, TableEnvironment 引入了一个用户类加载器，以在 table 程序、SQL Client、SQL Gateway 中保持一致的类加载行为。该类加载器会统一管理所有的用户 jar 包，包括通过 `ADD JAR` 或 `CREATE FUNCTION .. USING JAR ..` 添加的 jar 资源。
+ 在用户自定义连接器中，应该将 `Thread.currentThread().getContextClassLoader()` 替换成该用户类加载器去加载类。否则，可能会发生 `ClassNotFoundException` 的异常。该用户类加载器可以通过 `DynamicTableFactory.Context` 获得。
+{{< /hint >}}
概述
--------
diff --git a/docs/content.zh/docs/dev/table/sql/jar.md b/docs/content.zh/docs/dev/table/sql/jar.md
index 1440a7e7c09..c51698e20d5 100644
--- a/docs/content.zh/docs/dev/table/sql/jar.md
+++ b/docs/content.zh/docs/dev/table/sql/jar.md
@@ -80,8 +80,9 @@ ADD JAR '<path_to_filename>.jar'
添加一个 JAR 文件到资源列表中，该 jar 应该位于 Flink 当前支持的本地或远程[文件系统]({{< ref "docs/deployment/filesystems/overview" >}}) 中。添加的 JAR 文件可以使用 [`SHOW JARS`](#show-jars) 语句列出。
-### Limitation
-目前请不要通过 `ADD JAR` 语句来使用 Hive 连接器，正确行为参考 [Flink-Hive 集成]({{< ref "docs/connectors/table/hive/overview" >}}#dependencies).
+### 限制
+
+请不要通过 `ADD JAR` 语句来加载 Hive 的source、sink、function、catalog。这是 Hive connector 的一个已知限制，且会在将来版本中修复。当前，建议跟随这个指南来[安装 Hive 的集成]({{< ref "docs/connectors/table/hive/overview" >}}#dependencies)。
<a name="show-jars"></a>
diff --git a/docs/content/docs/dev/table/catalogs.md b/docs/content/docs/dev/table/catalogs.md
index 5f15cf68d31..ead4570284d 100644
--- a/docs/content/docs/dev/table/catalogs.md
+++ b/docs/content/docs/dev/table/catalogs.md
@@ -67,7 +67,9 @@ The factory is discovered using Java's Service Provider Interfaces (SPI).
Classes that implement this interface can be added to `META_INF/services/org.apache.flink.table.factories.Factory` in JAR files.
The provided factory identifier will be used for matching against the required `type` property in a SQL `CREATE CATALOG` DDL statement.
-Note: Since FLINK-15635, a user classloader is introduced to the table module to manage all user jars uniformly such as the jar added by `ADD JAR` statement. In custom catalogs, if some classes need to be loaded explicitly, please use the user classloader instead of thread context classloader. Otherwise, ClassNotFoundException maybe occur. Users can get the user classloader through `CatalogFactory.Context`.
+{{< hint warning >}}Since Flink v1.16, TableEnvironment introduces a user class loader to have a consistent class loading behavior in table programs, SQL Client and SQL Gateway. The user classloader manages all user jars such as jar added by `ADD JAR` or `CREATE FUNCTION .. USING JAR ..` statements.
+User-defined catalogs should replace `Thread.currentThread().getContextClassLoader()` with the user class loader to load classes. Otherwise, `ClassNotFoundException` maybe thrown. The user class loader can be accessed via `CatalogFactory.Context#getClassLoader`.
+{{< /hint >}}
## How to Create and Register Flink Tables to Catalog
diff --git a/docs/content/docs/dev/table/sourcesSinks.md b/docs/content/docs/dev/table/sourcesSinks.md
index eb8b538a1c9..4c019229de8 100644
--- a/docs/content/docs/dev/table/sourcesSinks.md
+++ b/docs/content/docs/dev/table/sourcesSinks.md
@@ -40,7 +40,9 @@ for more information about built-in table sources and sinks.
This page focuses on how to develop a custom, user-defined connector.
-Note: Since FLINK-15635, a user classloader is introduced to the table module to manage all user jars uniformly such as the jar added by `ADD JAR` statement. In user-defined connector, if some classes need to be loaded explicitly, please use the user classloader instead of thread context classloader. Otherwise, ClassNotFoundException maybe occur. Users can get the user classloader through `DynamicTableFactory.Context`.
+{{< hint warning >}}Since Flink v1.16, TableEnvironment introduces a user class loader to have a consistent class loading behavior in table programs, SQL Client and SQL Gateway. The user classloader manages all user jars such as jar added by `ADD JAR` or `CREATE FUNCTION .. USING JAR ..` statements.
+User-defined connectors should replace `Thread.currentThread().getContextClassLoader()` with the user class loader to load classes. Otherwise, `ClassNotFoundException` maybe thrown. The user class loader can be accessed via `DynamicTableFactory.Context`.
+{{< /hint >}}
Overview
--------
diff --git a/docs/content/docs/dev/table/sql/jar.md b/docs/content/docs/dev/table/sql/jar.md
index 640b3d8bd23..28008bb7e6e 100644
--- a/docs/content/docs/dev/table/sql/jar.md
+++ b/docs/content/docs/dev/table/sql/jar.md
@@ -76,7 +76,7 @@ ADD JAR '<path_to_filename>.jar'
Add a JAR file to the list of resources, it supports adding the jar locates in a local or remote [file system]({{< ref "docs/deployment/filesystems/overview" >}}). The added JAR file can be listed using [`SHOW JARS`](#show-jars) statements.
### Limitation
-Please don't use the hive connector by `ADD JAR` statement currently, the correct behavior refers to [Flink-Hive integration]({{< ref "docs/connectors/table/hive/overview" >}}#dependencies).
+Please don't use `ADD JAR` statement to load Hive source/sink/function/catalog. This is a known limitation of Hive connector and will be fixed in the future version. Currently, it's recommended to follow this [instruction]({{< ref "docs/connectors/table/hive/overview" >}}#dependencies) to setup Hive integration.
## SHOW JARS