[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 <fhue...@apache.org> Authored: Thu Mar 23 22:18:37 2017 +0100 Committer: Fabian Hueske <fhue...@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