Documentation

Author: jeffgbutler

CHANGELOG.md

@@ -6,6 +6,22 @@ This log will detail notable changes to MyBatis Dynamic SQL. Full details are av
 
 GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.4.1+](https://github.com/mybatis/mybatis-dynamic-sql/issues?q=milestone%3A1.4.1+)
 
+### Potentially Breaking Change
+
+In this release we have changed the default behavior of the library in one key area. If a where clause is coded,
+but fails to render because all the optional conditionals drop out of the where clause, then the library will now
+throw a `NonRenderingWhereClauseException`. We have made this change out of an abundance of caution. The prior
+behavior would allow generation of statements that inadvertently affected all rows in a table.
+
+Because of this change, we have also deprecated the "empty callback" functions in the "in" conditions.
+
+If you desire the prior behavior where non rendering where clauses are allowed, you can change the global configuration
+of the library or - even better - change the configuration of individual statements where this behavior should be allowed.
+
+For examples of global and statement configuration, see the "Configuration of the Library" page.
+
+### Other Changes
+
 1. Added support for criteria groups without an initial criteria. This makes it possible to create an independent list
    of pre-created criteria and then add the list to a where clause. See the tests in the related pull request for
    usage examples. ([#462](https://github.com/mybatis/mybatis-dynamic-sql/pull/462))
@@ -15,6 +31,9 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
 3. Updated the Kotlin DSL to use Kotlin 1.7's new "definitely non-null" types where appropriate. This helps us to more
    accurately represent the nullable/non-nullable expectations for API method calls.
    ([#496](https://github.com/mybatis/mybatis-dynamic-sql/pull/496))
+4. Added the ability to configure the library and change some default behaviors. Currently, this is limited to changing
+   the behavior of the library in regard to where clauses that will not render. See the new configuration page for
+   details.
 
 ## Release 1.4.0 - March 3, 2022
 

src/site/markdown/docs/configuration.md

@@ -0,0 +1,60 @@
+# Configuration of the Library
+
+Most behaviors of MyBatis Dynamic SQL are not configurable - the library does what it does.
+This page will detail the behaviors that can be modified. Configuration is available with version 1.4.1 and later
+of the library.
+
+The library can be configured globally - which will change the behavior for all statements - or each individual statement
+can be configured. There are sensible defaults for all configuration values, so configuration is not strictly necessary.
+If you want to change any of the default behaviors of the library, then the information on this page will help.
+
+Prior to version 1.4.1 of the library, there was no configurable behavior in the library. In version 1.4.1 we changed
+the default behavior of the library to throw an exception if a where clause fails to render. We did this out of an
+abundance of caution because the optional conditions in a where clause could lead to a statement that affected all
+rows in a table (for example, a delete statement could inadvertently delete all rows in a table). If you want the library
+to function as it did before version 1.4.1 where it was acceptable to have a where clause that didn't render, then you
+can change the global configuration as shown below.
+
+## Global Configuration
+
+On first use the library will initialize the global configuration. The global configuration can be changed via a property
+file named `mybatis-dynamic-sql.properties` in the root of the classpath. If you wish to use a different file name,
+you can specify the file name as a JVM property named `mybatis-dynamic-sql.configurationFile`. Note that the global
+configuration is created one time and shared for every statement in the same JVM.
+
+The configuration file is a standard Java properties file. The possible values are detailed in the next section.
+
+## Global Configuration Properties
+
+| Property                       | Default | Meaning                                                                                                                                                                                                                                                                                              |
+|--------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| nonRenderingWhereClauseAllowed | false   | If a where clause is specified, but fails to render, then the library will throw a `NonRenderingWhereClauseException` by default. If you set this value to true, then no exception will be thrown. This could cause statements to be rendered without where clauses that affect all rows in a table. |
+
+## Statement Configuration
+
+If the global configuration is not acceptable for any individual statement, you can also configure the statement in the
+DSL. Consider the following statement: 
+
+```java
+DeleteStatementProvider deleteStatement = deleteFrom(animalData)
+    .where(id, isNotIn(null, 22, null).filter(Objects::nonNull).filter(i -> i != 22))
+    .configureStatement(c -> c.setNonRenderingWhereClauseAllowed(true))
+    .build()
+    .render(RenderingStrategies.MYBATIS3);
+```
+
+In this case, the `isNotIn` condition has filters that will remove all values from the condition. In that case, the
+condition will not render and, subsequently, the where clause will not render. This means that the generated delete
+statement would delete all rows in the table. By default, the global configuration will block this statement from
+rendering and throw a `NonRenderingWhereClauseException`. If for some reason you would like to allow a statement
+like this to be rendered, then you can allow it as shown above with the `configureStatement` method.
+
+The Kotlin DSL contains the same function:
+
+```kotlin
+val deleteStatement = deleteFrom(person) {
+    where { id isNotEqualToWhenPresent null }
+    configureStatement { isNonRenderingWhereClauseAllowed = true } 
+}
+```
+

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/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" >
         <item href="docs/conditions.html" name="WHERE Conditions"/>