Docs

Author: jeffgbutler

CHANGELOG.md

@@ -31,7 +31,9 @@ Other important changes:
   With this change, the exception thrown is more predictable and the error is caught before sending the SQL to the
   database.
 - All the paging methods (limit, offset, fetchFirst) now have "WhenPresent" variations that will drop the phrase from
-  rendering if a null value is passed in 
+  rendering if a null value is passed in
+- The JOIN syntax is updated and now allows full boolean expressions like a WHERE clause. The prior JOIN syntax
+  is deprecated and will be removed in a future release.
 
 ## Release 1.5.2 - June 3, 2024
 

src/site/markdown/docs/kotlinOverview.md

@@ -417,9 +417,9 @@ val selectStatement = select(orderMaster.orderId, orderMaster.orderDate, orderDe
    orderDetail.description, orderDetail.quantity
 ) {
    from(orderMaster, "om")
-   join(orderDetail, "od") {
-      on(orderMaster.orderId) equalTo orderDetail.orderId
-      and(orderMaster.orderId) equalTo orderDetail.orderId
+   join(orderDetail, "od") on {
+      orderMaster.orderId isEqualTo orderDetail.orderId
+      and { orderMaster.orderId isEqualTo orderDetail.orderId }
    }
    where { orderMaster.orderId isEqualTo 1 }
    or {
@@ -433,8 +433,7 @@ val selectStatement = select(orderMaster.orderId, orderMaster.orderDate, orderDe
 
 In a select statement you must specify a table in a `from` clause. Everything else is optional.
 
-Multiple join clauses can be specified if you need to join additional tables. In a join clause, you must
-specify an `on` condition, and you may specify additional `and` conditions as necessary. Full, left, right, inner,
+Multiple join clauses can be specified if you need to join additional tables. Full, left, right, inner,
 and outer joins are supported.
 
 Where clauses can be of arbitrary complexity and support all SQL operators including exists operators, subqueries, etc.

src/site/markdown/docs/migratingV1toV2.md

@@ -0,0 +1,69 @@
+# V1 to V2 Migration Guide
+
+Version 2 of MyBatis Dynamic SQL introduced many new features. This page will document how to migrate code
+from prior releases to version 2.
+
+## Java Join Syntax
+
+Version2 offers a fully flexible join specification and reuses the capabilities of where clauses. Of course,
+not all capabilities are supported in databases, but you should now be able to code any type of join specification.
+
+The changes in the Java DSL are mostly internal and should not impact most users. The `equalTo` methods has been
+deprecated in favor of `isEqualTo`, but all other changes should be hidden.
+
+V1 Join Specification Example:
+```java
+SelectStatementProvider selectStatement = select(orderMaster.orderId, orderDetail.lineNumber, orderDetail.quantity)
+        .from(orderMaster, "om")
+        .join(orderDetail, "od", on(orderMaster.orderId, equalTo(orderDetail.orderId)))
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
+```
+
+V2 Join Specification Example:
+```java
+SelectStatementProvider selectStatement = select(orderMaster.orderId, orderDetail.lineNumber, orderDetail.quantity)
+        .from(orderMaster, "om")
+        .join(orderDetail, "od", on(orderMaster.orderId, isEqualTo(orderDetail.orderId)))
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
+```
+
+## Kotlin Join Syntax
+
+Like the Java DSL, the V2 Kotlin DSL offers a fully flexible join specification and reuses the capabilities of where
+clauses. Of course, not all capabilities are supported in databases, but you should now be able to code any type of
+join specification.
+
+The changes in the Kotlin DSL allow a more natural expressions of a join specification. The main difference is that
+the "on" keyword should be moved outside the join specification lambda (it is now an infix function). Inside the lambda,
+the conditions should be rewritten to match the syntax of a where clause.
+
+V1 Join Specification Example:
+```kotlin
+val selectStatement = select(
+    orderMaster.orderId, orderMaster.orderDate,
+    orderDetail.lineNumber, orderDetail.description, orderDetail.quantity
+) {
+    from(orderMaster, "om")
+    join(orderDetail, "od") {
+        on(orderMaster.orderId) equalTo orderDetail.orderId
+        and(orderMaster.orderId) equalTo constant("1")
+    }
+}
+```
+
+V2 Join Specification Example:
+```kotlin
+val selectStatement = select(
+    orderMaster.orderId, orderMaster.orderDate,
+    orderDetail.lineNumber, orderDetail.description, orderDetail.quantity
+) {
+    from(orderMaster, "om")
+    join(orderDetail, "od") on {
+        orderMaster.orderId isEqualTo orderDetail.orderId
+        and { orderMaster.orderId isEqualTo constant("1") }
+    }
+}
+
+```

src/site/markdown/docs/select.md

@@ -10,7 +10,7 @@ In general, the following are supported:
 2. Tables can be aliased per select statement
 3. Columns can be aliased per select statement
 4. Some support for aggregates (avg, min, max, sum)
-5. Equijoins of type INNER, LEFT OUTER, RIGHT OUTER, FULL OUTER
+5. Joins of type INNER, LEFT OUTER, RIGHT OUTER, FULL OUTER
 6. Subqueries in where clauses. For example, `where foo in (select foo from foos where id < 36)`
 7. Select from another select. For example `select count(*) from (select foo from foos where id < 36)`
 8. Multi-Selects. For example `(select * from foo order by id limit 3) union (select * from foo order by id desc limit 3)`
@@ -21,47 +21,50 @@ At this time, the library does not support the following:
 2. INTERSECT, EXCEPT, etc.
 
 The user guide page for WHERE Clauses shows examples of many types of SELECT statements with different complexities of
-the WHERE clause including support for sub-queries.  We will just show a single example here, including an ORDER BY clause:
+the WHERE clause including support for sub-queries.  We will just show a single example here, including an ORDER BY
+clause:
 
 ```java
-    SelectStatementProvider selectStatement = select(id, animalName, bodyWeight, brainWeight)
-            .from(animalData)
-            .where(id, isIn(1, 5, 7))
-            .and(bodyWeight, isBetween(1.0).and(3.0))
-            .orderBy(id.descending(), bodyWeight)
-            .build()
-            .render(RenderingStrategies.MYBATIS3);
-
-    List<AnimalData> animals = mapper.selectMany(selectStatement);
+SelectStatementProvider selectStatement = select(id, animalName, bodyWeight, brainWeight)
+        .from(animalData)
+        .where(id, isIn(1, 5, 7))
+        .and(bodyWeight, isBetween(1.0).and(3.0))
+        .orderBy(id.descending(), bodyWeight)
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
+
+List<AnimalData> animals = mapper.selectMany(selectStatement);
 ```
 
 The WHERE and ORDER BY clauses are optional.
 
 ## Joins
-The library supports the generation of equijoin statements - joins defined by column matching.  For example:
+The library supports the generation of join statements.  For example:
 
 ```java
-    SelectStatementProvider selectStatement = select(orderMaster.orderId, orderDate, orderDetail.lineNumber, orderDetail.description, orderDetail.quantity)
-            .from(orderMaster, "om")
-            .join(orderDetail, "od").on(orderMaster.orderId, equalTo(orderDetail.orderId))
-            .build()
-            .render(RenderingStrategies.MYBATIS3);
+SelectStatementProvider selectStatement = select(orderMaster.orderId, orderDate, orderDetail.lineNumber, orderDetail.description, orderDetail.quantity)
+        .from(orderMaster, "om")
+        .join(orderDetail, "od").on(orderMaster.orderId, isEqualTo(orderDetail.orderId))
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
 ```
 
-Notice that you can give an alias to a table if desired. If you don't specify an alias, the full table name will be used in the generated SQL.
+Notice that you can give an alias to a table if desired. If you don't specify an alias, the full table name will be
+used in the generated SQL.
 
 Multiple tables can be joined in a single statement. 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);
+SelectStatementProvider selectStatement = select(orderMaster.orderId, orderDate, orderLine.lineNumber, itemMaster.description, orderLine.quantity)
+        .from(orderMaster, "om")
+        .join(orderLine, "ol").on(orderMaster.orderId, isEqualTo(orderLine.orderId))
+        .join(itemMaster, "im").on(orderLine.itemId, isEqualTo(itemMaster.itemId))
+        .where(orderMaster.orderId, isEqualTo(2))
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
 ```
-Join queries will likely require you to define a MyBatis result mapping in XML. This is the only instance where XML is required.  This is due to the limitations of the MyBatis annotations when mapping collections.
+Join queries will likely require you to define a MyBatis result mapping in XML. This is the only instance where XML is
+required.  This is due to the limitations of the MyBatis annotations when mapping collections.
 
 The library supports four join types:
 
@@ -74,14 +77,14 @@ The library supports four join types:
 The library supports the generation of UNION and UNION ALL queries. For example:
 
 ```java
-    SelectStatementProvider selectStatement = select(id, animalName, bodyWeight, brainWeight)
-            .from(animalData)
-            .union()
-            .selectDistinct(id, animalName, bodyWeight, brainWeight)
-            .from(animalData)
-            .orderBy(id)
-            .build()
-            .render(RenderingStrategies.MYBATIS3);
+SelectStatementProvider selectStatement = select(id, animalName, bodyWeight, brainWeight)
+        .from(animalData)
+        .union()
+        .selectDistinct(id, animalName, bodyWeight, brainWeight)
+        .from(animalData)
+        .orderBy(id)
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
 ```
 
 Any number of SELECT statements can be added to a UNION query. Only one ORDER BY phrase is allowed.
@@ -96,16 +99,16 @@ Multi-select queries are a special case of union select statements. The differen
 paging clauses can be applied to the merged queries. For example:
 
 ```java
-    SelectStatementProvider selectStatement = multiSelect(
-            select(id, animalName, bodyWeight, brainWeight)
-            .from(animalData)
-            .orderBy(id)
-            .limit(2)
+SelectStatementProvider selectStatement = multiSelect(
+        select(id, animalName, bodyWeight, brainWeight)
+                .from(animalData)
+                .orderBy(id)
+                .limit(2)
         ).union(
-            selectDistinct(id, animalName, bodyWeight, brainWeight)
-            .from(animalData)
-            .orderBy(id.descending())
-            .limit(3)
+                selectDistinct(id, animalName, bodyWeight, brainWeight)
+                .from(animalData)
+                .orderBy(id.descending())
+                .limit(3)
         )
         .build()
         .render(RenderingStrategies.MYBATIS3);
@@ -114,7 +117,8 @@ paging clauses can be applied to the merged queries. For example:
 ## 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):
+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):
 
 ```java
 import org.apache.ibatis.annotations.Result;
@@ -143,7 +147,9 @@ import org.mybatis.dynamic.sql.util.SqlProviderAdapter;
 
 ## XML Mapper for Join Statements
 
-If you are coding a join, it is likely you will need to code an XML mapper to define the result map. This is due to a MyBatis limitation - the annotations cannot define a collection mapping. If you have to do this, the Java code looks like this:
+If you are coding a join, it is likely you will need to code an XML mapper to define the result map. This is due to a
+MyBatis limitation - the annotations cannot define a collection mapping. If you have to do this, the Java code looks
+like this:
 
 ```java
     @SelectProvider(type=SqlProviderAdapter.class, method="select")
@@ -171,7 +177,8 @@ And the corresponding XML looks like this:
 Notice that the resultMap is the only element in the XML mapper. This is our recommended practice.
 
 ## XML Mapper for Select Statements
-We do not recommend using an XML mapper for select statements, but if you want to do so the SelectStatementProvider object can be used as a parameter to a MyBatis mapper method directly.
+We do not recommend using an XML mapper for select statements, but if you want to do so the SelectStatementProvider
+object can be used as a parameter to a MyBatis mapper method directly.
 
 If you are using an XML mapper, the select method should look like this in the Java interface:
 
@@ -205,30 +212,33 @@ Order by phrases can be difficult to calculate when there are aliased columns, a
 This library has taken a relatively simple approach:
 
 1. When specifying an SqlColumn in an ORDER BY phrase the library will either write the column alias or the column
-name into the ORDER BY phrase.  For the ORDER BY phrase, the table alias (if there is one) will be ignored. Use this pattern
-when the ORDER BY column is a member of the select list. For example `orderBy(foo)`. If the column has an alias, then
-it is easist to use the "arbitrary string" method with the column alias as shown below.
-1. It is also possible to explicitly specify a table alias for a column in an ORDER BY phrase. Use this pattern when
-there is a join, and the ORDER BY column is in two or more tables, and the ORDER BY column is not in the select
-list. For example `orderBy(sortColumn("t1", foo))`.
-1. If none of the above use cases meet your needs, then you can specify an arbitrary String to write into the rendered ORDER BY
-phrase (see below for an example).
+   name into the ORDER BY phrase.  For the ORDER BY phrase, the table alias (if there is one) will be ignored. Use this
+   pattern when the ORDER BY column is a member of the select list. For example `orderBy(foo)`. If the column has an
+   alias, then it is easiest to use the "arbitrary string" method with the column alias as shown below.
+2. It is also possible to explicitly specify a table alias for a column in an ORDER BY phrase. Use this pattern when
+   there is a join, and the ORDER BY column is in two or more tables, and the ORDER BY column is not in the select
+   list. For example `orderBy(sortColumn("t1", foo))`.
+3. If none of the above use cases meet your needs, then you can specify an arbitrary String to write into the rendered
+   ORDER BY phrase (see below for an example).
 
 In our testing, this caused an issue in only one case.  When there is an outer join and the select list contains
 both the left and right join column.  In that case, the workaround is to supply a column alias for both columns.
 
-When using a column function (lower, upper, etc.), then it is customary to give the calculated column an alias so you will have a predictable result set.  In cases like this there will not be a column to use for an alias.  The library supports arbitrary values in an ORDER BY expression like this:
+When using a column function (lower, upper, etc.), then it is customary to give the calculated column an alias so you
+will have a predictable result set.  In cases like this there will not be a column to use for an alias.  The library
+supports arbitrary values in an ORDER BY expression like this:
 
 ```java
-    SelectStatementProvider selectStatement = select(substring(gender, 1, 1).as("ShortGender"), avg(age).as("AverageAge"))
-            .from(person, "a")
-            .groupBy(substring(gender, 1, 1))
-            .orderBy(sortColumn("ShortGender").descending())
-            .build()
-            .render(RenderingStrategies.MYBATIS3);
+SelectStatementProvider selectStatement = select(substring(gender, 1, 1).as("ShortGender"), avg(age).as("AverageAge"))
+        .from(person, "a")
+        .groupBy(substring(gender, 1, 1))
+        .orderBy(sortColumn("ShortGender").descending())
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
 ```
 
-In this example the `substring` function is used in both the select list and the GROUP BY expression.  In the ORDER BY expression, we use the `sortColumn` function to duplicate the alias given to the column in the select list.
+In this example the `substring` function is used in both the select list and the GROUP BY expression.  In the ORDER BY
+expression, we use the `sortColumn` function to duplicate the alias given to the column in the select list.
 
 ## Limit and Offset Support
 Since version 1.1.1 the select statement supports limit and offset for paging (or slicing) queries. You can specify:
@@ -237,18 +247,22 @@ Since version 1.1.1 the select statement supports limit and offset for paging (o
 - Offset only
 - Both limit and offset
 
-It is important to note that the select renderer writes limit and offset clauses into the generated select statement as is. The library does not attempt to normalize those values for databases that don't support limit and offset directly. Therefore, it is very important for users to understand whether or not the target database supports limit and offset. If the target database does not support limit and offset, then it is likely that using this support will create SQL that has runtime errors.
+It is important to note that the select renderer writes limit and offset clauses into the generated select statement as
+is. The library does not attempt to normalize those values for databases that don't support limit and offset directly.
+Therefore, it is very important for users to understand whether the target database supports limit and offset.
+If the target database does not support limit and offset, then it is likely that using this support will create SQL
+that has runtime errors.
 
 An example follows:
 
 ```java
-    SelectStatementProvider selectStatement = select(animalData.allColumns())
-            .from(animalData)
-            .orderBy(id)
-            .limit(3)
-            .offset(22)
-            .build()
-            .render(RenderingStrategies.MYBATIS3);
+SelectStatementProvider selectStatement = select(animalData.allColumns())
+        .from(animalData)
+        .orderBy(id)
+        .limit(3)
+        .offset(22)
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
 ```
 
 ## Fetch First Support
@@ -263,11 +277,11 @@ Fetch first is an SQL standard and is supported by most databases.
 An example follows:
 
 ```java
-    SelectStatementProvider selectStatement = select(animalData.allColumns())
-            .from(animalData)
-            .orderBy(id)
-            .offset(22)
-            .fetchFirst(3).rowsOnly()
-            .build()
-            .render(RenderingStrategies.MYBATIS3);
+SelectStatementProvider selectStatement = select(animalData.allColumns())
+        .from(animalData)
+        .orderBy(id)
+        .offset(22)
+        .fetchFirst(3).rowsOnly()
+        .build()
+        .render(RenderingStrategies.MYBATIS3);
 ```

src/site/site.xml

@@ -36,6 +36,7 @@
     <menu name="User's Guide">
       <item href="docs/introduction.html" name="Introduction" />
       <item href="docs/CHANGELOG.html" name="Change Log" />
+      <item href="docs/migratingV1toV2.html" name="Migrating from V1 to V2" />
       <item href="docs/quickStart.html" name="Quick Start" />
       <item href="docs/exceptions.html" name="Exceptions thrown by the Library" />
       <item href="docs/configuration.html" name="Configuration of the Library" />