You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flink.apache.org by fh...@apache.org on 2017/03/30 22:04:33 UTC
[22/50] [abbrv] flink git commit: [hotfix] [table] Improved code
documentation for external catalog.
[hotfix] [table] Improved code documentation for external catalog.
Project: http://git-wip-us.apache.org/repos/asf/flink/repo
Commit: http://git-wip-us.apache.org/repos/asf/flink/commit/f97deaa9
Tree: http://git-wip-us.apache.org/repos/asf/flink/tree/f97deaa9
Diff: http://git-wip-us.apache.org/repos/asf/flink/diff/f97deaa9
Branch: refs/heads/table-retraction
Commit: f97deaa9683bf1868ecf104c73b997ede63e8856
Parents: 135a57c
Author: Fabian Hueske <fh...@apache.org>
Authored: Thu Mar 23 22:18:37 2017 +0100
Committer: Fabian Hueske <fh...@apache.org>
Committed: Fri Mar 24 20:19:17 2017 +0100
----------------------------------------------------------------------
.../flink/table/annotation/TableType.java | 6 +-
.../table/catalog/CrudExternalCatalog.scala | 86 ++++++++++----------
.../flink/table/catalog/ExternalCatalog.scala | 40 ++++-----
.../table/catalog/ExternalCatalogDatabase.scala | 6 +-
.../table/catalog/ExternalCatalogTable.scala | 24 +++---
.../table/catalog/TableSourceConverter.scala | 23 +++---
6 files changed, 94 insertions(+), 91 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/flink/blob/f97deaa9/flink-libraries/flink-table/src/main/java/org/apache/flink/table/annotation/TableType.java
----------------------------------------------------------------------
diff --git a/flink-libraries/flink-table/src/main/java/org/apache/flink/table/annotation/TableType.java b/flink-libraries/flink-table/src/main/java/org/apache/flink/table/annotation/TableType.java
index 1cebe53..3845eae 100644
--- a/flink-libraries/flink-table/src/main/java/org/apache/flink/table/annotation/TableType.java
+++ b/flink-libraries/flink-table/src/main/java/org/apache/flink/table/annotation/TableType.java
@@ -27,7 +27,7 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
- * A {@link TableSourceConverter} with this annotation bind the converter with table type.
+ * Annotates a table type of a {@link TableSourceConverter}.
*/
@Documented
@Target(ElementType.TYPE)
@@ -36,9 +36,9 @@ import java.lang.annotation.Target;
public @interface TableType {
/**
- * Specifies the external catalog table type of {@link TableSourceConverter}.
+ * Returns the table type of a {@link TableSourceConverter}.
*
- * @return the external catalog table type of {@link TableSourceConverter}.
+ * @return The table type of the {@link TableSourceConverter}.
*/
String value();
http://git-wip-us.apache.org/repos/asf/flink/blob/f97deaa9/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/CrudExternalCatalog.scala
----------------------------------------------------------------------
diff --git a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/CrudExternalCatalog.scala b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/CrudExternalCatalog.scala
index d93f140..fcefa45 100644
--- a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/CrudExternalCatalog.scala
+++ b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/CrudExternalCatalog.scala
@@ -21,88 +21,86 @@ package org.apache.flink.table.catalog
import org.apache.flink.table.api._
/**
- * This class is responsible for interact with external catalog.
- * Its main responsibilities including:
- * <ul>
- * <li> create/drop/alter database or tables for DDL operations
- * <li> provide tables for calcite catalog, it looks up databases or tables in the external catalog
- * </ul>
+ * The CrudExternalCatalog provides methods to create, drop, and alter databases or tables.
*/
trait CrudExternalCatalog extends ExternalCatalog {
/**
- * Adds table into external Catalog
+ * Adds a table to the catalog.
*
- * @param table description of table which to create
- * @param ignoreIfExists if table already exists in the catalog, not throw exception and leave
- * the existed table if ignoreIfExists is true;
- * else throw a TableAlreadyExistException.
- * @throws DatabaseNotExistException if database does not exist in the catalog yet
- * @throws TableAlreadyExistException if table already exists in the catalog and
- * ignoreIfExists is false
+ * @param table Description of the table to add
+ * @param ignoreIfExists Flag to specify behavior if a table with the given name already exists:
+ * if set to false, it throws a TableAlreadyExistException,
+ * if set to true, nothing happens.
+ * @throws DatabaseNotExistException thrown if database does not exist
+ * @throws TableAlreadyExistException thrown if table already exists and ignoreIfExists is false
*/
@throws[DatabaseNotExistException]
@throws[TableAlreadyExistException]
def createTable(table: ExternalCatalogTable, ignoreIfExists: Boolean): Unit
/**
- * Deletes table from external Catalog
+ * Deletes table from a database of the catalog.
*
- * @param dbName database name
- * @param tableName table name
- * @param ignoreIfNotExists if table not exist yet, not throw exception if ignoreIfNotExists is
- * true; else throw TableNotExistException
- * @throws DatabaseNotExistException if database does not exist in the catalog yet
- * @throws TableNotExistException if table does not exist in the catalog yet
+ * @param dbName Name of the database
+ * @param tableName Name of the table
+ * @param ignoreIfNotExists Flag to specify behavior if the table or database does not exist:
+ * if set to false, throw an exception,
+ * if set to true, nothing happens.
+ * @throws DatabaseNotExistException thrown if the database does not exist in the catalog
+ * @throws TableNotExistException thrown if the table does not exist in the catalog
*/
@throws[DatabaseNotExistException]
@throws[TableNotExistException]
def dropTable(dbName: String, tableName: String, ignoreIfNotExists: Boolean): Unit
/**
- * Modifies an existing table in the external catalog
+ * Modifies an existing table in the catalog.
*
- * @param table description of table which to modify
- * @param ignoreIfNotExists if the table not exist yet, not throw exception if ignoreIfNotExists
- * is true; else throw TableNotExistException
- * @throws DatabaseNotExistException if database does not exist in the catalog yet
- * @throws TableNotExistException if table does not exist in the catalog yet
+ * @param table New description of the table to update
+ * @param ignoreIfNotExists Flag to specify behavior if the table or database does not exist:
+ * if set to false, throw an exception,
+ * if set to true, nothing happens.
+ * @throws DatabaseNotExistException thrown if the database does not exist in the catalog
+ * @throws TableNotExistException thrown if the table does not exist in the catalog
*/
@throws[DatabaseNotExistException]
@throws[TableNotExistException]
def alterTable(table: ExternalCatalogTable, ignoreIfNotExists: Boolean): Unit
/**
- * Adds database into external Catalog
+ * Adds a database to the catalog.
*
- * @param db description of database which to create
- * @param ignoreIfExists if database already exists in the catalog, not throw exception and leave
- * the existed database if ignoreIfExists is true;
- * else throw a DatabaseAlreadyExistException.
- * @throws DatabaseAlreadyExistException if database already exists in the catalog and
- * ignoreIfExists is false
+ * @param db Description of the database to create
+ * @param ignoreIfExists Flag to specify behavior if a database with the given name already
+ * exists: if set to false, it throws a DatabaseAlreadyExistException,
+ * if set to true, nothing happens.
+ * @throws DatabaseAlreadyExistException thrown if the database does already exist in the catalog
+ * and ignoreIfExists is false
*/
@throws[DatabaseAlreadyExistException]
def createDatabase(db: ExternalCatalogDatabase, ignoreIfExists: Boolean): Unit
/**
- * Deletes database from external Catalog
+ * Deletes a database from the catalog.
*
- * @param dbName database name
- * @param ignoreIfNotExists if database not exist yet, not throw exception if ignoreIfNotExists
- * is true; else throw DatabaseNotExistException
- * @throws DatabaseNotExistException if database does not exist in the catalog yet
+ * @param dbName Name of the database.
+ * @param ignoreIfNotExists Flag to specify behavior if the database does not exist:
+ * if set to false, throw an exception,
+ * if set to true, nothing happens.
+ * @throws DatabaseNotExistException thrown if the database does not exist in the catalog
*/
@throws[DatabaseNotExistException]
def dropDatabase(dbName: String, ignoreIfNotExists: Boolean): Unit
/**
- * Modifies existed database into external Catalog
+ * Modifies an existing database in the catalog.
*
- * @param db description of database which to modify
- * @param ignoreIfNotExists if database not exist yet, not throw exception if ignoreIfNotExists
- * is true; else throw DatabaseNotExistException
- * @throws DatabaseNotExistException if database does not exist in the catalog yet
+ * @param db New description of the database to update
+ * @param ignoreIfNotExists Flag to specify behavior if the database does not exist:
+ * if set to false, throw an exception,
+ * if set to true, nothing happens.
+ * @throws DatabaseNotExistException thrown if the database does not exist in the catalog
*/
@throws[DatabaseNotExistException]
def alterDatabase(db: ExternalCatalogDatabase, ignoreIfNotExists: Boolean): Unit
http://git-wip-us.apache.org/repos/asf/flink/blob/f97deaa9/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalog.scala
----------------------------------------------------------------------
diff --git a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalog.scala b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalog.scala
index 58b62c7..00a35e4 100644
--- a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalog.scala
+++ b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalog.scala
@@ -23,49 +23,51 @@ import java.util.{List => JList}
import org.apache.flink.table.api._
/**
- * This class is responsible for read table/database from external catalog.
- * Its main responsibilities is provide tables for calcite catalog, it looks up databases or tables
- * in the external catalog.
+ * An [[ExternalCatalog]] is the connector between an external database catalog and Flink's
+ * Table API.
+ *
+ * It provides information about databases and tables such as names, schema, statistics, and
+ * access information.
*/
trait ExternalCatalog {
/**
- * Gets table from external Catalog
+ * Get a table from the catalog
*
- * @param dbName database name
- * @param tableName table name
- * @throws DatabaseNotExistException if database does not exist in the catalog yet
- * @throws TableNotExistException if table does not exist in the catalog yet
- * @return found table
+ * @param dbName The name of the table's database.
+ * @param tableName The name of the table.
+ * @throws DatabaseNotExistException thrown if the database does not exist in the catalog.
+ * @throws TableNotExistException thrown if the table does not exist in the catalog.
+ * @return the requested table
*/
@throws[DatabaseNotExistException]
@throws[TableNotExistException]
def getTable(dbName: String, tableName: String): ExternalCatalogTable
/**
- * Gets the table name lists from current external Catalog
+ * Get a list of all table names of a database in the catalog.
*
- * @param dbName database name
- * @throws DatabaseNotExistException if database does not exist in the catalog yet
- * @return lists of table name
+ * @param dbName The name of the database.
+ * @throws DatabaseNotExistException thrown if the database does not exist in the catalog
+ * @return The list of table names
*/
@throws[DatabaseNotExistException]
def listTables(dbName: String): JList[String]
/**
- * Gets database from external Catalog
+ * Gets a database from the catalog.
*
- * @param dbName database name
- * @throws DatabaseNotExistException if database does not exist in the catalog yet
- * @return found database
+ * @param dbName The name of the database.
+ * @throws DatabaseNotExistException thrown if the database does not exist in the catalog
+ * @return The requested database
*/
@throws[DatabaseNotExistException]
def getDatabase(dbName: String): ExternalCatalogDatabase
/**
- * Gets the database name lists from current external Catalog
+ * Gets a list of all databases in the catalog.
*
- * @return list of database names
+ * @return The list of database names
*/
def listDatabases(): JList[String]
http://git-wip-us.apache.org/repos/asf/flink/blob/f97deaa9/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogDatabase.scala
----------------------------------------------------------------------
diff --git a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogDatabase.scala b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogDatabase.scala
index c2a4702..99ab2eb 100644
--- a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogDatabase.scala
+++ b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogDatabase.scala
@@ -21,10 +21,10 @@ package org.apache.flink.table.catalog
import java.util.{HashMap => JHashMap, Map => JMap}
/**
- * Database definition of the external catalog.
+ * Defines a database in an [[ExternalCatalog]].
*
- * @param dbName database name
- * @param properties database properties
+ * @param dbName The name of the database
+ * @param properties The properties of the database
*/
case class ExternalCatalogDatabase(
dbName: String,
http://git-wip-us.apache.org/repos/asf/flink/blob/f97deaa9/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogTable.scala
----------------------------------------------------------------------
diff --git a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogTable.scala b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogTable.scala
index 893cbb3..4fdab66 100644
--- a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogTable.scala
+++ b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/ExternalCatalogTable.scala
@@ -26,16 +26,16 @@ import org.apache.flink.table.api.TableSchema
import org.apache.flink.table.plan.stats.TableStats
/**
- * Table definition of the external catalog.
+ * Defines a table in an [[ExternalCatalog]].
*
- * @param identifier identifier of external catalog table, including dbName and tableName
- * @param tableType type of external catalog table, e.g csv, hbase, kafka
- * @param schema schema of table data, including column names and column types
- * @param properties properties of external catalog table
- * @param stats statistics of external catalog table
- * @param comment comment of external catalog table
- * @param createTime create time of external catalog table
- * @param lastAccessTime last access time of of external catalog table
+ * @param identifier Identifier of the table (database name and table name)
+ * @param tableType Table type, e.g csv, hbase, kafka
+ * @param schema Schema of the table (column names and types)
+ * @param properties Properties of the table
+ * @param stats Statistics of the table
+ * @param comment Comment of the table
+ * @param createTime Create timestamp of the table
+ * @param lastAccessTime Timestamp of last access of the table
*/
case class ExternalCatalogTable(
identifier: TableIdentifier,
@@ -48,10 +48,10 @@ case class ExternalCatalogTable(
lastAccessTime: JLong = -1L)
/**
- * Identifier of external catalog table
+ * Identifier for a catalog table.
*
- * @param database database name
- * @param table table name
+ * @param database Database name
+ * @param table Table name
*/
case class TableIdentifier(
database: String,
http://git-wip-us.apache.org/repos/asf/flink/blob/f97deaa9/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/TableSourceConverter.scala
----------------------------------------------------------------------
diff --git a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/TableSourceConverter.scala b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/TableSourceConverter.scala
index 13e54a6..ca6df9a 100644
--- a/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/TableSourceConverter.scala
+++ b/flink-libraries/flink-table/src/main/scala/org/apache/flink/table/catalog/TableSourceConverter.scala
@@ -22,26 +22,29 @@ import java.util.{Set => JSet}
import org.apache.flink.table.sources.TableSource
-/** Defines a converter used to convert [[org.apache.flink.table.sources.TableSource]] to
- * or from [[ExternalCatalogTable]].
+/** Creates a [[org.apache.flink.table.sources.TableSource]] from the properties of an
+ * [[ExternalCatalogTable]].
*
- * @tparam T The tableSource which to do convert operation on.
+ * The [[org.apache.flink.table.annotation.TableType]] annotation defines which type of external
+ * table is supported.
+ *
+ * @tparam T The [[TableSource]] to be created by this converter.
*/
trait TableSourceConverter[T <: TableSource[_]] {
/**
- * Defines the required properties that must exists in the properties of an ExternalCatalogTable
- * to ensure the input ExternalCatalogTable is compatible with the requirements of
- * current converter.
- * @return the required properties.
+ * Defines the properties that need to be provided by the [[ExternalCatalogTable]] to create
+ * the [[TableSource]].
+ *
+ * @return The required properties.
*/
def requiredProperties: JSet[String]
/**
- * Converts the input external catalog table instance to a tableSource instance.
+ * Creates a [[TableSource]] for the given [[ExternalCatalogTable]].
*
- * @param externalCatalogTable input external catalog table instance to convert
- * @return converted tableSource instance from input external catalog table.
+ * @param externalCatalogTable ExternalCatalogTable to create a TableSource from.
+ * @return The created TableSource.
*/
def fromExternalCatalogTable(externalCatalogTable: ExternalCatalogTable): T