You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In this example, the three conditions will only be rendered if the values passed to them are not null. If all three values are null, then no where clause will be generated.
89
+
In this example, the three conditions will only be rendered if the values passed to them are not null.
90
+
If all three values are null, then no where clause will be generated.
86
91
87
-
Each of the conditions accepts a lambda expression that can be used to determine if the condition should render or not. The lambdas will all be of standard JDK types (either `java.util.function.BooleanSupplier`, `java.util.function.Predicate`, or `java.util.function.BiPredicate` depending on the type of condition). The following table lists the optional conditions and shows how to use them:
92
+
Each of the conditions accepts a lambda expression that can be used to determine if the condition should render or not.
93
+
The lambdas will all be of standard JDK types (either `java.util.function.BooleanSupplier`,
94
+
`java.util.function.Predicate`, or `java.util.function.BiPredicate` depending on the type of condition). The following
95
+
table lists the optional conditions and shows how to use them:
88
96
89
97
| Condition | Example | Rendering Rules |
90
98
|-----------|---------|-----------------|
@@ -103,8 +111,9 @@ Each of the conditions accepts a lambda expression that can be used to determine
103
111
| Not Null | where(id, isNotNull().when(BooleanSupplier) | The condition will render if BooleanSupplier.getAsBoolean() returns true |
104
112
| Null | where(id, isNull().when(BooleanSupplier) | The condition will render if BooleanSupplier.getAsBoolean() returns true |
105
113
106
-
### "When Present" Optional Conditions
107
-
The library supplies several specializations of optional conditions to be used in the common case of checking for null values. The table below lists the rendering rules for each of these "when present" optional conditions.
114
+
### "When Present" Condition Builders
115
+
The library supplies several methods that supply conditions to be used in the common case of checking for null
116
+
values. The table below lists the rendering rules for each of these "when present" condition builder methods.
108
117
109
118
| Condition | Example | Rendering Rules |
110
119
|-----------|---------|-----------------|
@@ -121,12 +130,33 @@ The library supplies several specializations of optional conditions to be used i
121
130
| Not Like | where(id, isNotLikeWhenPresent(x)) | The condition will render if x is non-null |
122
131
| Not Like Case Insensitive | where(id, isNotLikeCaseInsensitiveWhenPresent(x)) | The condition will render if x is non-null |
123
132
124
-
### Optionality with the "In" Conditions
125
-
Optionality with the "in" and "not in" conditions is a bit more complex than the other types of conditions. The first thing to know is that no "in" or "not in" condition will render if the list of values is empty. For example, there will never be rendered SQL like `where name in ()`. So optionality of the "in" conditions is more about optionality of the *values* of the condition. The library comes with functions that will filter out null values, and will upper case String values to enable case insensitive queries. There are extension points to add additional filtering and mapping if you so desire.
133
+
Note that these methods simply apply a "NotNull" filter to a condition. For example:
126
134
127
-
We think it is a good thing that the library will not render invalid SQL. An "in" condition will always be dropped from rendering if the list of values is empty. But there is some danger with this stance. Because the condition could be dropped from the rendered SQL, more rows could be impacted than expected if the list ends up empty for whatever reason. Our recommended solution is to make sure that you validate list values - especially if they are coming from direct user input. Another option is to take some action when the list is empty. This can be especially helpful when you are applying filters to the value list or using one of the built in "when present" conditions. In that case, it is possible that the list of values could end up empty after a validation check.
135
+
```java
136
+
// the following two lines are functionally equivalent
137
+
... where (id, isEqualToWhenPresent(x)) ...
138
+
... where (id, isEqualTo(x).filter(Objects::nonNull)) ...
139
+
```
128
140
129
-
The "In" conditions support a callback that will be invoked when the value list is empty and just before the statement is rendered. You could use the callback to create a condition that will throw an exception when the list is empty. For example:
141
+
### Optionality with the "In" Conditions
142
+
Optionality with the "in" and "not in" conditions is a bit more complex than the other types of conditions. The first
143
+
thing to know is that no "in" or "not in" condition will render if the list of values is empty. For example, there
144
+
will never be rendered SQL like `where name in ()`. So optionality of the "in" conditions is more about optionality
145
+
of the *values* of the condition. The library comes with functions that will filter out null values, and will upper
146
+
case String values to enable case insensitive queries. There are extension points to add additional filtering and
147
+
mapping if you so desire.
148
+
149
+
We think it is a good thing that the library will not render invalid SQL. An "in" condition will always be dropped from
150
+
rendering if the list of values is empty. But there is some danger with this stance. Because the condition could be
151
+
dropped from the rendered SQL, more rows could be impacted than expected if the list ends up empty for whatever reason.
152
+
Our recommended solution is to make sure that you validate list values - especially if they are coming from direct user
153
+
input. Another option is to take some action when the list is empty. This can be especially helpful when you are
154
+
applying filters to the value list or using one of the built-in "when present" conditions. In that case, it is
155
+
possible that the list of values could end up empty after a validation check.
156
+
157
+
The "In" conditions support a callback that will be invoked when the value list is empty and just before the statement
158
+
is rendered. You could use the callback to create a condition that will throw an exception when the list is empty.
@@ -139,7 +169,8 @@ The "In" conditions support a callback that will be invoked when the value list
139
169
}
140
170
```
141
171
142
-
The following table shows the different supplied In conditions and how they will render for different sets of inputs. The table assumes the following types of input:
172
+
The following table shows the different supplied In conditions and how they will render for different sets of inputs.
173
+
The table assumes the following types of input:
143
174
144
175
- Example 1 assumes an input list of ("foo", null, "bar") - like `where(name, isIn("foo", null, "bar"))`
145
176
- Example 2 assumes an input list of (null) - like `where(name, isIn((String)null))`
@@ -156,35 +187,39 @@ The following table shows the different supplied In conditions and how they will
156
187
| IsNotInCaseInsensitive | No | Yes | upper(name) not in ('FOO', null, 'BAR') | upper(name) not in (null) |
157
188
| IsNotInCaseInsensitiveWhenPresent | Yes | Yes | upper(name) not in ('FOO', 'BAR') | No Render |
158
189
159
-
If none of these options meet your needs, there is an extension point where you can add your own filter and/or map conditions to the value stream. This gives you great flexibility to alter or filter the value list before the condition is rendered.
190
+
If none of these options meet your needs, the "In" conditions also support "map" and "filter" methods for the values.
191
+
This gives you great flexibility to alter or filter the value list before the condition
192
+
is rendered.
160
193
161
-
The extension point for modifying the value list is the method `then(UnaryOperator<Stream<T>>)`. This method accepts a `UnaryOperator<Stream<T>>` in which you can specify map and/or filter operations for the value stream. For example, suppose you wanted to code an "in" condition that accepted a list of strings, but you want to filter out any null or blank string, and you want to trim all strings. This can be accomplished with code like this:
194
+
For example, suppose you wanted to code an "in" condition that accepted a list of strings, but you want to filter out
195
+
any null or blank string, and you want to trim all strings. This can be accomplished with code like this:
0 commit comments