Add AliasableSQLColumn

Author: jeffgbutler

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 This log will detail notable changes to MyBatis Dynamic SQL. Full details are available on the GitHub milestone pages.
 
+## Release 1.3.1 - Unreleased
+
+GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.3.1+](https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.3.1+)
+
+### Added
+
+- Added the ability to specify a JavaType associated with a column. The JavaType will be rendered properly for MyBatis ([#386](https://github.com/mybatis/mybatis-dynamic-sql/pull/386))
+- Added a few missing groupBy and orderBy methods on the `select` statement ([#409](https://github.com/mybatis/mybatis-dynamic-sql/pull/409))
+- Added a new extension of SqlTable that supports setting a table alias directly within the table definition
+
 ## Release 1.3.0 - May 6, 2021
 
 GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.3.0+](https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.3.0+)

src/main/java/org/mybatis/dynamic/sql/AliasableSqlTable.java

@@ -0,0 +1,47 @@
+/*
+ *    Copyright 2016-2021 the original author or authors.
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+package org.mybatis.dynamic.sql;
+
+import java.util.Objects;
+import java.util.Optional;
+import java.util.function.Supplier;
+
+public abstract class AliasableSqlTable<T extends AliasableSqlTable<T>> extends SqlTable {
+
+    private String tableAlias;
+    private final Supplier<T> constructor;
+
+    protected AliasableSqlTable(String tableName, Supplier<T> constructor) {
+        super(tableName);
+        this.constructor = Objects.requireNonNull(constructor);
+    }
+
+    protected AliasableSqlTable(Supplier<String> tableNameSupplier, Supplier<T> constructor) {
+        super(tableNameSupplier);
+        this.constructor = Objects.requireNonNull(constructor);
+    }
+
+    public T withAlias(String alias) {
+        T newTable = constructor.get();
+        ((AliasableSqlTable<T>) newTable).tableAlias = alias;
+        return newTable;
+    }
+
+    @Override
+    public Optional<String> tableAlias() {
+        return Optional.ofNullable(tableAlias);
+    }
+}

src/main/java/org/mybatis/dynamic/sql/SqlTable.java

@@ -1,5 +1,5 @@
 /*
- *    Copyright 2016-2020 the original author or authors.
+ *    Copyright 2016-2021 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -108,6 +108,10 @@ public <R> R accept(TableExpressionVisitor<R> visitor) {
         return visitor.visit(this);
     }
 
+    public Optional<String> tableAlias() {
+        return Optional.empty();
+    }
+
     public static SqlTable of(String name) {
         return new SqlTable(name);
     }

src/main/java/org/mybatis/dynamic/sql/render/TableAliasCalculator.java

@@ -1,5 +1,5 @@
 /*
- *    Copyright 2016-2020 the original author or authors.
+ *    Copyright 2016-2021 the original author or authors.
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -32,11 +32,20 @@ protected TableAliasCalculator(Map<SqlTable, String> aliases) {
     }
 
     public Optional<String> aliasForColumn(SqlTable table) {
-        return Optional.ofNullable(aliases.get(table));
+        return explicitAliasOrTableAlias(table);
     }
 
     public Optional<String> aliasForTable(SqlTable table) {
-        return Optional.ofNullable(aliases.get(table));
+        return explicitAliasOrTableAlias(table);
+    }
+
+    private Optional<String> explicitAliasOrTableAlias(SqlTable table) {
+        String alias = aliases.get(table);
+        if (alias == null) {
+            return table.tableAlias();
+        } else {
+            return Optional.of(alias);
+        }
     }
 
     public static TableAliasCalculator of(SqlTable table, String alias) {

src/site/markdown/docs/databaseObjects.md

@@ -141,6 +141,88 @@ public static final class User extends SqlTable {
 
 Whenever the table is referenced for rendering SQL, the name will be calculated based on the current value of the system property.
 
+## Aliased Tables
+
+In join queries, it is usually a good practice to specify table aliases. The `select` statement includes
+support for specifying table aliases in each query in a way that looks like natural SQL. For example:
+
+```java
+    SelectStatementProvider selectStatement = select(orderMaster.orderId, orderDate, orderLine.lineNumber, itemMaster.description, orderLine.quantity)
+            .from(orderMaster, "om")
+            .join(orderLine, "ol").on(orderMaster.orderId, equalTo(orderLine.orderId))
+            .join(itemMaster, "im").on(orderLine.itemId, equalTo(itemMaster.itemId))
+            .where(orderMaster.orderId, isEqualTo(2))
+            .build()
+            .render(RenderingStrategies.MYBATIS3);
+```
+
+In a query like this, the library will automatically append the table alias to the column name when the query is rendered.
+Internally, the alias for a column is determined by looking up the associated table in a HashMap maintained within the
+query model. If you do not specify a table alias, the library will automatically append the table name in join queries.
+
+Unfortunately, this strategy fails for self-joins. It can also get confusing when there are sub-queries. Imagine a
+query like this:
+
+```java
+    SelectStatementProvider selectStatement = select(user.userId, user.userName, user.parentId)
+            .from(user, "u1")
+            .join(user, "u2").on(user.userId, equalTo(user.parentId))
+            .where(user.userId, isEqualTo(4))
+            .build()
+            .render(RenderingStrategies.MYBATIS3);
+```
+
+In this query it is not clear which instance of the `user` table is used for each column, and there will only be entry in the
+HashMap for the `user` table - so only one of the aliases specified in the select statement will be in effect.
+There are two ways to deal with this problem.
+
+The first is to simply create another instance of the User SqlTable object. With this method it is very clear which column
+belongs to which instance of the table and the library can easily calculate aliases:
+
+```java
+    User user1 = new User();
+    User user2 = new User();
+    SelectStatementProvider selectStatement = select(user1.userId, user1.userName, user1.parentId)
+            .from(user1, "u1")
+            .join(user2, "u2").on(user1.userId, equalTo(user2.parentId))
+            .where(user2.userId, isEqualTo(4))
+            .build()
+            .render(RenderingStrategies.MYBATIS3);
+```
+
+Starting with version 1.3.1, there is new method where the alias can be specified in the table object itself. This allows
+you to move the aliases out of the `select` statement.
+
+```java
+    User user1 = user.withAlias("u1");
+    User user2 = user.withAlias("u2");
+
+    SelectStatementProvider selectStatement = select(user1.userId, user1.userName, user1.parentId)
+            .from(user1)
+            .join(user2).on(user1.userId, equalTo(user2.parentId))
+            .where(user2.userId, isEqualTo(4))
+            .build()
+            .render(RenderingStrategies.MYBATIS3);
+```
+
+To enable this support, your table objects should extend `org.mybatis.dynamic.sql.AliasableSqlTable` rather than
+`org.mybatis.dynamic.sql.SqlTable` as follows:
+
+```java
+    public static final class User extends AliasableSqlTable<User> {
+        public final SqlColumn<Integer> userId = column("user_id", JDBCType.INTEGER);
+        public final SqlColumn<String> userName = column("user_name", JDBCType.VARCHAR);
+        public final SqlColumn<Integer> parentId = column("parent_id", JDBCType.INTEGER);
+
+        public User() {
+            super("User", User::new);
+        }
+    }
+```
+
+If you use an aliased table object, and also specify an alias in the `select` statement, the alias from the `select`
+statement will override the alias in the table object.
+
 ## Column Representation
 
 The class `org.mybatis.dynamic.sql.SqlColumn` is used to represent a column in a table or view. An `SqlColumn` is always

src/site/markdown/docs/select.md

@@ -85,7 +85,7 @@ The library supports the generation of UNION and UNION ALL queries. For example:
 
 Any number of SELECT statements can be added to a UNION query. Only one ORDER BY phrase is allowed.
 
-## Annotated Mapper for Select Statements
+## MyBatis Mapper for Select Statements
 
 The SelectStatementProvider object can be used as a parameter to a MyBatis mapper method directly. If you
 are using an annotated mapper, the select method should look like this (note that we recommend coding a "selectMany" and a "selectOne" method with a shared result mapping):

src/test/java/examples/joins/JoinMapperTest.java

@@ -958,6 +958,68 @@ void testSelfWithDuplicateAlias() {
         ).withMessage("Table \"User\" with requested alias \"u2\" is already aliased in this query with alias \"u1\". Attempting to re-alias a table in the same query is not supported.");
     }
 
+    @Test
+    void testSelfWithNewAlias() {
+        try (SqlSession session = sqlSessionFactory.openSession()) {
+            JoinMapper mapper = session.getMapper(JoinMapper.class);
+
+            // create second table instance for self-join
+            UserDynamicSQLSupport.User user2 = user.withAlias("u2");
+
+            // get Bamm Bamm's parent - should be Barney
+            SelectStatementProvider selectStatement = select(user.userId, user.userName, user.parentId)
+                    .from(user)
+                    .join(user2).on(user.userId, equalTo(user2.parentId))
+                    .where(user2.userId, isEqualTo(4))
+                    .build()
+                    .render(RenderingStrategies.MYBATIS3);
+
+            String expectedStatement = "select User.user_id, User.user_name, User.parent_id"
+                    + " from User join User u2 on User.user_id = u2.parent_id"
+                    + " where u2.user_id = #{parameters.p1,jdbcType=INTEGER}";
+            assertThat(selectStatement.getSelectStatement()).isEqualTo(expectedStatement);
+
+            List<User> rows = mapper.selectUsers(selectStatement);
+
+            assertThat(rows).hasSize(1);
+            User row = rows.get(0);
+            assertThat(row.getUserId()).isEqualTo(2);
+            assertThat(row.getUserName()).isEqualTo("Barney");
+            assertThat(row.getParentId()).isNull();
+        }
+    }
+
+    @Test
+    void testSelfWithNewAliasAndOverride() {
+        try (SqlSession session = sqlSessionFactory.openSession()) {
+            JoinMapper mapper = session.getMapper(JoinMapper.class);
+
+            // create second table instance for self-join
+            UserDynamicSQLSupport.User user2 = user.withAlias("other_user");
+
+            // get Bamm Bamm's parent - should be Barney
+            SelectStatementProvider selectStatement = select(user.userId, user.userName, user.parentId)
+                    .from(user, "u1")
+                    .join(user2, "u2").on(user.userId, equalTo(user2.parentId))
+                    .where(user2.userId, isEqualTo(4))
+                    .build()
+                    .render(RenderingStrategies.MYBATIS3);
+
+            String expectedStatement = "select u1.user_id, u1.user_name, u1.parent_id"
+                    + " from User u1 join User u2 on u1.user_id = u2.parent_id"
+                    + " where u2.user_id = #{parameters.p1,jdbcType=INTEGER}";
+            assertThat(selectStatement.getSelectStatement()).isEqualTo(expectedStatement);
+
+            List<User> rows = mapper.selectUsers(selectStatement);
+
+            assertThat(rows).hasSize(1);
+            User row = rows.get(0);
+            assertThat(row.getUserId()).isEqualTo(2);
+            assertThat(row.getUserName()).isEqualTo("Barney");
+            assertThat(row.getParentId()).isNull();
+        }
+    }
+
     @Test
     void testLimitAndOffsetAfterJoin() {
         try (SqlSession session = sqlSessionFactory.openSession()) {

src/test/java/examples/joins/UserDynamicSQLSupport.java

@@ -17,22 +17,22 @@
 
 import java.sql.JDBCType;
 
+import org.mybatis.dynamic.sql.AliasableSqlTable;
 import org.mybatis.dynamic.sql.SqlColumn;
-import org.mybatis.dynamic.sql.SqlTable;
 
 public class UserDynamicSQLSupport {
     public static final User user = new User();
     public final SqlColumn<Integer> userId = user.userId;
     public final SqlColumn<String> userName = user.userName;
     public final SqlColumn<Integer> parentId = user.parentId;
 
-    public static final class User extends SqlTable {
+    public static final class User extends AliasableSqlTable<User> {
         public final SqlColumn<Integer> userId = column("user_id", JDBCType.INTEGER);
         public final SqlColumn<String> userName = column("user_name", JDBCType.VARCHAR);
         public final SqlColumn<Integer> parentId = column("parent_id", JDBCType.INTEGER);
 
         public User() {
-            super("User");
+            super("User", User::new);
         }
     }
 }