Add documentation for exceptions

Author: jeffgbutler

src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/KInvalidSQLException.kt

@@ -15,9 +15,9 @@
  */
 package org.mybatis.dynamic.sql.util.kotlin
 
-import org.mybatis.dynamic.sql.exception.DynamicSqlException
+import org.mybatis.dynamic.sql.exception.InvalidSqlException
 
 /**
  * This exception is thrown if the library detects misuse of the Kotlin DSL that would result in invalid SQL
  */
-class KInvalidSQLException(message: String) : DynamicSqlException(message)
+class KInvalidSQLException(message: String) : InvalidSqlException(message)

src/site/markdown/docs/exceptions.md

@@ -0,0 +1,53 @@
+# Exceptions Thrown by the Library
+
+The library will throw runtime exceptions in a variety of cases - most often when invalid SQL is detected.
+
+All exceptions are derived from `org.mybatis.dynamic.sql.exception.DynamicSqlException` which is, in turn,
+derived from `java.lang.RuntimeException`.
+
+The most important exceptions to think about are `InvalidSQLException` and `NonRenderingWhereClauseException`. We
+provide details about those exceptions below.
+
+## Invalid SQL Detection
+
+The library makes an effort to prevent the generation of invalid SQL. If invalid SQL is detected, the library will
+throw `InvalidSQLException` or one of it's derived exceptions. Invalid SQL can happen in different ways:
+
+1. Misuse of the DSL. For example, the DSL allows you to build an update statement with no "set" clauses.
+   Even though technically allowed by the DSL, this would produce invalid SQL.
+2. Misuse of the Kotlin DSL. The Kotlin DSL provides a lot of flexibility for building statements and looks very close
+   to native SQL, but that flexibility can be misused. For example, the Kotlin DSL would allow you to write an insert
+   statement without an "into" clause.
+3. More common is a case when using the optional mappings in an insert or update statement. It is possible
+   that all mappings would fail to render which would produce invalid SQL. For example, in a general insert statement
+   you could specify many "set column to value when present" mappings that all had null values. All mappings would fail
+   to render in that case which would cause invalid SQL.
+
+All of these exceptions can be avoided through proper use of the DSL and validation of input values.
+
+## Non Rendering Where Clauses
+
+Most conditions in a where clause provide optionality - they have `filter` methods that can cause the condition to be
+dropped from the where clause. If all the conditions in a where clause fail to render, then the where clause itself is
+dropped from the rendered SQL. This can be dangerous in that it can cause a statement to be generated that affects all
+rows in a table. For example, all rows could be deleted. As of version 1.4.1, the library will throw a 
+`NonRenderingWhereClauseException` in this case out of an abundance of caution. This behavior can be overridden
+through either global configuration, or by configuring individual statements to allow for where clauses to be dropped.
+
+The important idea is that there are legitimate cases when it is reasonable to allow a where clause to not render, but
+the decision to allow that should be very intentional. See the "Configuration of the Library" page for further details.
+
+The exception will only be thrown if a where clause is coded but fails to render. If you do not code a where clause in
+a statement, then we assume that you intend for all rows to be affected.
+
+## Exception Details
+
+Details of the different exceptions follows:
+
+| Exception                                                            | Causes                                                                                                                                                                                                                                                                            |
+|----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `org.mybatis.dynamic.sql.exception.DuplicateTableAliasException`     | Thrown if you attempt to join more than one table with the same alias in a select statement                                                                                                                                                                                       |
+| `org.mybatis.dynamic.sql.exception.DynamicSQLException`              | Thrown when other more specific exceptions are not appropriate. One example is when reading a configuration property file causes an IOException. This is a rare occurrence.                                                                                                       |
+| `org.mybatis.dynamic.sql.exception.InvalidSQLException`              | Thrown if invalid SQL is detected. The most common causes are when all the optional column mappings in an insert or update statement fail to render.                                                                                                                              |
+| `org.mybatis.dynamic.sql.exception.NonRenderingWhereClauseException` | Thrown if all conditions in a where clause fail to render - which will cause the where clause to be dropped from the rendered SQL. This could cause a statement to inadvertently affect all rows in a table. This behavior can be changed with global or statement configuration. |
+| `org.mybatis.dynamic.sql.util.kotlin.KInvalidSqlException`           | Thrown if invalid SQL is detected when using the Kotlin DSL. This exception is for specific misuses of the Kotlin DSL. It is derived from `InvalidSQLException` which can also occur when using the Kotlin DSL.                                                                   |

src/site/site.xml

@@ -37,6 +37,7 @@
       <item href="docs/introduction.html" name="Introduction" />
       <item href="docs/CHANGELOG.html" name="Change Log" />
       <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" />
       <item href="docs/databaseObjects.html" name="Modeling Database Objects" />
       <item href="docs/whereClauses.html" name="WHERE Clause Support" >