From 80a107ca99b845876ee037511b596ac6ed3ccbcb Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Thu, 4 Jul 2013 10:52:46 +0200 Subject: [PATCH] Reorganised methods in org.jooq.Table --- jOOQ/src/main/java/org/jooq/Table.java | 408 +++++++++++++------------ 1 file changed, 210 insertions(+), 198 deletions(-) diff --git a/jOOQ/src/main/java/org/jooq/Table.java b/jOOQ/src/main/java/org/jooq/Table.java index 2678ba76d9..3eb37cb8b9 100644 --- a/jOOQ/src/main/java/org/jooq/Table.java +++ b/jOOQ/src/main/java/org/jooq/Table.java @@ -100,86 +100,6 @@ public interface Table extends TableLike { */ Class getRecordType(); - /** - * Create an alias for this table. - *

- * Note that the case-sensitivity of the returned table depends on - * {@link Settings#getRenderNameStyle()}. By default, table aliases are - * quoted, and thus case-sensitive! - * - * @param alias The alias name - * @return The table alias - */ - @Support - @Transition( - name = "AS", - to = "AliasedTable", - args = "String" - ) - Table as(String alias); - - /** - * Create an alias for this table and its fields - *

- * Note that the case-sensitivity of the returned table and columns depends - * on {@link Settings#getRenderNameStyle()}. By default, table aliases are - * quoted, and thus case-sensitive! - *

- *

Derived column lists for table references
- *

- * Note, not all databases support derived column lists for their table - * aliases. On the other hand, some databases do support derived column - * lists, but only for derived tables. jOOQ will try to turn table - * references into derived tables to make this syntax work. In other words, - * the following statements are equivalent: 

-     * -- Using derived column lists to rename columns (e.g. Postgres)
-     * SELECT t.a, t.b
-     * FROM my_table t(a, b)
-     *
-     * -- Nesting table references within derived tables (e.g. SQL Server)
-     * SELECT t.a, t.b
-     * FROM (
-     *   SELECT * FROM my_table
-     * ) t(a, b)
-     *
- *

- *

Derived column lists for derived tables
- *

- * Other databases may not support derived column lists at all, but they do - * support common table expressions. The following statements are - * equivalent: 

-     * -- Using derived column lists to rename columns (e.g. Postgres)
-     * SELECT t.a, t.b
-     * FROM (
-     *   SELECT 1, 2
-     * ) AS t(a, b)
-     *
-     * -- Using UNION ALL to produce column names (e.g. MySQL)
-     * SELECT t.a, t.b
-     * FROM (
-     *   SELECT null a, null b FROM DUAL WHERE 1 = 0
-     *   UNION ALL
-     *   SELECT 1, 2 FROM DUAL
-     * ) t
-     *
- * - * @param alias The alias name - * @param fieldAliases The field aliases. Excess aliases are ignored, - * missing aliases will be substituted by this table's field - * names. - * @return The table alias - */ - @Support - @Transition( - name = "AS", - to = "AliasedTable", - args = { - "String", - "String+" - } - ) - Table as(String alias, String... fieldAliases); - /** * Retrieve the table's IDENTITY information, if available. *

@@ -298,132 +218,93 @@ public interface Table extends TableLike { */ List> getReferencesTo(Table other); - /** - * Specify a SQL Server style table hint for query optimisation - *

- * This makes sense only on an actual database table or view, not on other - * composed table sources. - *

- * Example: - *

- * 

-     * create.select()
-     *       .from(BOOK.as("b").with("READUNCOMMITTED")
-     *       .fetch();
-     *
- *

- * For {@link SQLDialect#ORACLE} style hints, see - * {@link SelectFromStep#hint(String)} and {@link SelectQuery#addHint(String)} - * - * @see http://msdn.microsoft.com/en-us/library/ms187373.aspx - * @see SelectFromStep#hint(String) - * @see SelectQuery#addHint(String) - */ - @Support({ SQLSERVER, SYBASE }) - @Transition( - name = "WITH", - args = "String" - ) - Table with(String hint); + // ------------------------------------------------------------------------- + // XXX: Aliasing clauses + // ------------------------------------------------------------------------- /** - * Create a new TABLE reference from this table, pivoting it - * into another form + * Create an alias for this table. *

- * This has been observed to work with - *

    - *
  • {@link SQLDialect#ORACLE11G} upwards
    • - *
  • {@link SQLDialect#SQLSERVER} (not yet officially supported)
    • - *
  • Other dialects by using some means of simulation (not yet officially - * supported)
    • - *
+ * Note that the case-sensitivity of the returned table depends on + * {@link Settings#getRenderNameStyle()}. By default, table aliases are + * quoted, and thus case-sensitive! * - * @param aggregateFunctions The aggregate functions used for pivoting. - * @return A DSL object to create the PIVOT expression - */ - @Support({ ORACLE11G, ORACLE12C }) - @Transition( - name = "PIVOT", - args = "Field+" - ) - PivotForStep pivot(Field... aggregateFunctions); - - /** - * Create a new TABLE reference from this table, pivoting it - * into another form - *

- * For more details, see {@link #pivot(Field...)} - * - * @param aggregateFunctions The aggregate functions used for pivoting. - * @return A DSL object to create the PIVOT expression - * @see #pivot(Field...) - */ - @Support({ ORACLE11G, ORACLE12C }) - @Transition( - name = "PIVOT", - args = "Field+" - ) - PivotForStep pivot(Collection> aggregateFunctions); - - /** - * Create a new TABLE reference from this table, applying - * relational division. - *

- * Relational division is the inverse of a cross join operation. The - * following is an approximate definition of a relational division: - * 

-     * Assume the following cross join / cartesian product
-     * C = A × B
-     *
-     * Then it can be said that
-     * A = C ÷ B
-     * B = C ÷ A
-     *
- *

- * With jOOQ, you can simplify using relational divisions by using the - * following syntax: 

-     * C.divideBy(B).on(C.ID.equal(B.C_ID)).returning(C.TEXT)
-     *
- *

- * The above roughly translates to 

-     * SELECT DISTINCT C.TEXT FROM C "c1"
-     * WHERE NOT EXISTS (
-     *   SELECT 1 FROM B
-     *   WHERE NOT EXISTS (
-     *     SELECT 1 FROM C "c2"
-     *     WHERE "c2".TEXT = "c1".TEXT
-     *     AND "c2".ID = B.C_ID
-     *   )
-     * )
-     *
- *

- * Or in plain text: Find those TEXT values in C whose ID's correspond to - * all ID's in B. Note that from the above SQL statement, it is immediately - * clear that proper indexing is of the essence. Be sure to have indexes on - * all columns referenced from the on(...) and - * returning(...) clauses. - *

- * For more information about relational division and some nice, real-life - * examples, see - *

- *

- * This has been observed to work with all dialects + * @param alias The alias name + * @return The table alias */ @Support @Transition( - name = "DIVIDE BY", - args = "Table" + name = "AS", + to = "AliasedTable", + args = "String" ) - DivideByOnStep divideBy(Table divisor); + Table as(String alias); + + /** + * Create an alias for this table and its fields + *

+ * Note that the case-sensitivity of the returned table and columns depends + * on {@link Settings#getRenderNameStyle()}. By default, table aliases are + * quoted, and thus case-sensitive! + *

+ *

Derived column lists for table references
+ *

+ * Note, not all databases support derived column lists for their table + * aliases. On the other hand, some databases do support derived column + * lists, but only for derived tables. jOOQ will try to turn table + * references into derived tables to make this syntax work. In other words, + * the following statements are equivalent: 

+     * -- Using derived column lists to rename columns (e.g. Postgres)
+     * SELECT t.a, t.b
+     * FROM my_table t(a, b)
+     *
+     * -- Nesting table references within derived tables (e.g. SQL Server)
+     * SELECT t.a, t.b
+     * FROM (
+     *   SELECT * FROM my_table
+     * ) t(a, b)
+     *
+ *

+ *

Derived column lists for derived tables
+ *

+ * Other databases may not support derived column lists at all, but they do + * support common table expressions. The following statements are + * equivalent: 

+     * -- Using derived column lists to rename columns (e.g. Postgres)
+     * SELECT t.a, t.b
+     * FROM (
+     *   SELECT 1, 2
+     * ) AS t(a, b)
+     *
+     * -- Using UNION ALL to produce column names (e.g. MySQL)
+     * SELECT t.a, t.b
+     * FROM (
+     *   SELECT null a, null b FROM DUAL WHERE 1 = 0
+     *   UNION ALL
+     *   SELECT 1, 2 FROM DUAL
+     * ) t
+     *
+ * + * @param alias The alias name + * @param fieldAliases The field aliases. Excess aliases are ignored, + * missing aliases will be substituted by this table's field + * names. + * @return The table alias + */ + @Support + @Transition( + name = "AS", + to = "AliasedTable", + args = { + "String", + "String+" + } + ) + Table as(String alias, String... fieldAliases); + + // ------------------------------------------------------------------------- + // XXX: JOIN clauses on tables + // ------------------------------------------------------------------------- /** * Join a table to this table using a {@link JoinType} @@ -1020,4 +901,135 @@ public interface Table extends TableLike { to = "JoinedTable" ) Table naturalRightOuterJoin(String sql, QueryPart... parts); + + // ------------------------------------------------------------------------- + // XXX: Exotic and vendor-specific clauses on tables + // ------------------------------------------------------------------------- + + /** + * Specify a SQL Server style table hint for query optimisation + *

+ * This makes sense only on an actual database table or view, not on other + * composed table sources. + *

+ * Example: + *

+ * 

+     * create.select()
+     *       .from(BOOK.as("b").with("READUNCOMMITTED")
+     *       .fetch();
+     *
+ *

+ * For {@link SQLDialect#ORACLE} style hints, see + * {@link SelectFromStep#hint(String)} and {@link SelectQuery#addHint(String)} + * + * @see http://msdn.microsoft.com/en-us/library/ms187373.aspx + * @see SelectFromStep#hint(String) + * @see SelectQuery#addHint(String) + */ + @Support({ SQLSERVER, SYBASE }) + @Transition( + name = "WITH", + args = "String" + ) + Table with(String hint); + + /** + * Create a new TABLE reference from this table, pivoting it + * into another form + *

+ * This has been observed to work with + *

    + *
  • {@link SQLDialect#ORACLE11G} upwards
    • + *
  • {@link SQLDialect#SQLSERVER} (not yet officially supported)
    • + *
  • Other dialects by using some means of simulation (not yet officially + * supported)
    • + *
+ * + * @param aggregateFunctions The aggregate functions used for pivoting. + * @return A DSL object to create the PIVOT expression + */ + @Support({ ORACLE11G, ORACLE12C }) + @Transition( + name = "PIVOT", + args = "Field+" + ) + PivotForStep pivot(Field... aggregateFunctions); + + /** + * Create a new TABLE reference from this table, pivoting it + * into another form + *

+ * For more details, see {@link #pivot(Field...)} + * + * @param aggregateFunctions The aggregate functions used for pivoting. + * @return A DSL object to create the PIVOT expression + * @see #pivot(Field...) + */ + @Support({ ORACLE11G, ORACLE12C }) + @Transition( + name = "PIVOT", + args = "Field+" + ) + PivotForStep pivot(Collection> aggregateFunctions); + + /** + * Create a new TABLE reference from this table, applying + * relational division. + *

+ * Relational division is the inverse of a cross join operation. The + * following is an approximate definition of a relational division: + * 

+     * Assume the following cross join / cartesian product
+     * C = A × B
+     *
+     * Then it can be said that
+     * A = C ÷ B
+     * B = C ÷ A
+     *
+ *

+ * With jOOQ, you can simplify using relational divisions by using the + * following syntax: 

+     * C.divideBy(B).on(C.ID.equal(B.C_ID)).returning(C.TEXT)
+     *
+ *

+ * The above roughly translates to 

+     * SELECT DISTINCT C.TEXT FROM C "c1"
+     * WHERE NOT EXISTS (
+     *   SELECT 1 FROM B
+     *   WHERE NOT EXISTS (
+     *     SELECT 1 FROM C "c2"
+     *     WHERE "c2".TEXT = "c1".TEXT
+     *     AND "c2".ID = B.C_ID
+     *   )
+     * )
+     *
+ *

+ * Or in plain text: Find those TEXT values in C whose ID's correspond to + * all ID's in B. Note that from the above SQL statement, it is immediately + * clear that proper indexing is of the essence. Be sure to have indexes on + * all columns referenced from the on(...) and + * returning(...) clauses. + *

+ * For more information about relational division and some nice, real-life + * examples, see + *

+ *

+ * This has been observed to work with all dialects + */ + @Support + @Transition( + name = "DIVIDE BY", + args = "Table" + ) + DivideByOnStep divideBy(Table divisor); }