flink-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fhue...@apache.org
Subject [22/50] [abbrv] flink git commit: [hotfix] [table] Improved code documentation for external catalog.
Date Thu, 30 Mar 2017 22:04:33 GMT
[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 <fhueske@apache.org>
Authored: Thu Mar 23 22:18:37 2017 +0100
Committer: Fabian Hueske <fhueske@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
 


Mime
View raw message