Source code

001package io.ebean;
002
003import java.util.Collection;
004import java.util.Map;
005
006/**
007 * Expression factory for creating standard expressions for WHERE and HAVING
008 * clauses.
009 * <p>
010 * Generally you will only need to use this object for creating OR, JUNCTION or
011 * CONJUNCTION expressions. To create simple expressions you will most likely
012 * just use the methods on the ExpressionList object that is returned via
013 * {@link Query#where()}.
014 * </p>
015 * <p>
016 * This provides a convenient way to create expressions for the default
017 * database.
018 * <p>
019 * See also {@link DB#getExpressionFactory()}
020 * </p>
021 * <p>
022 * Creates standard common expressions for using in a Query Where or Having
023 * clause.
024 * </p>
025 *
026 * @see Query#where()
027 */
028public class Expr {
029
030  private Expr() {
031  }
032
033  /**
034   * Equal To - property equal to the given value.
035   */
036  public static Expression eq(String propertyName, Object value) {
037    return DB.getExpressionFactory().eq(propertyName, value);
038  }
039
040  /**
041   * Not Equal To - property not equal to the given value.
042   */
043  public static Expression ne(String propertyName, Object value) {
044    return DB.getExpressionFactory().ne(propertyName, value);
045  }
046
047  /**
048   * Case Insensitive Equal To - property equal to the given value (typically
049   * using a lower() function to make it case insensitive).
050   */
051  public static Expression ieq(String propertyName, String value) {
052    return DB.getExpressionFactory().ieq(propertyName, value);
053  }
054
055  /**
056   * In Range - {@code property >= value1 and property < value2}.
057   * <p>
058   * Unlike Between inRange is "half open" and usually more useful for use with dates or timestamps.
059   * </p>
060   */
061  public static Expression inRange(String propertyName, Object value1, Object value2) {
062    return DB.getExpressionFactory().inRange(propertyName, value1, value2);
063  }
064
065  /**
066   * Between - property between the two given values.
067   */
068  public static Expression between(String propertyName, Object value1, Object value2) {
069    return DB.getExpressionFactory().between(propertyName, value1, value2);
070  }
071
072  /**
073   * Between - value between two given properties.
074   */
075  public static Expression between(String lowProperty, String highProperty, Object value) {
076    return DB.getExpressionFactory().betweenProperties(lowProperty, highProperty, value);
077  }
078
079  /**
080   * Greater Than - property greater than the given value.
081   */
082  public static Expression gt(String propertyName, Object value) {
083    return DB.getExpressionFactory().gt(propertyName, value);
084  }
085
086  /**
087   * Greater Than or Equal to - property greater than or equal to the given
088   * value.
089   */
090  public static Expression ge(String propertyName, Object value) {
091    return DB.getExpressionFactory().ge(propertyName, value);
092  }
093
094  /**
095   * Less Than - property less than the given value.
096   */
097  public static Expression lt(String propertyName, Object value) {
098    return DB.getExpressionFactory().lt(propertyName, value);
099  }
100
101  /**
102   * Less Than or Equal to - property less than or equal to the given value.
103   */
104  public static Expression le(String propertyName, Object value) {
105    return DB.getExpressionFactory().le(propertyName, value);
106  }
107
108  /**
109   * Is Null - property is null.
110   */
111  public static Expression isNull(String propertyName) {
112    return DB.getExpressionFactory().isNull(propertyName);
113  }
114
115  /**
116   * Is Not Null - property is not null.
117   */
118  public static Expression isNotNull(String propertyName) {
119    return DB.getExpressionFactory().isNotNull(propertyName);
120  }
121
122  /**
123   * Case insensitive {@link #exampleLike(Object)}
124   */
125  public static ExampleExpression iexampleLike(Object example) {
126    return DB.getExpressionFactory().iexampleLike(example);
127  }
128
129  /**
130   * Create the query by Example expression which is case sensitive and using
131   * LikeType.RAW (you need to add you own wildcards % and _).
132   */
133  public static ExampleExpression exampleLike(Object example) {
134    return DB.getExpressionFactory().exampleLike(example);
135  }
136
137  /**
138   * Create the query by Example expression specifying more options.
139   */
140  public static ExampleExpression exampleLike(Object example, boolean caseInsensitive, LikeType likeType) {
141    return DB.getExpressionFactory().exampleLike(example, caseInsensitive, likeType);
142  }
143
144  /**
145   * Like - property like value where the value contains the SQL wild card
146   * characters % (percentage) and _ (underscore).
147   */
148  public static Expression like(String propertyName, String value) {
149    return DB.getExpressionFactory().like(propertyName, value);
150  }
151
152  /**
153   * Case insensitive Like - property like value where the value contains the
154   * SQL wild card characters % (percentage) and _ (underscore). Typically uses
155   * a lower() function to make the expression case insensitive.
156   */
157  public static Expression ilike(String propertyName, String value) {
158    return DB.getExpressionFactory().ilike(propertyName, value);
159  }
160
161  /**
162   * Starts With - property like value%.
163   */
164  public static Expression startsWith(String propertyName, String value) {
165    return DB.getExpressionFactory().startsWith(propertyName, value);
166  }
167
168  /**
169   * Case insensitive Starts With - property like value%. Typically uses a
170   * lower() function to make the expression case insensitive.
171   */
172  public static Expression istartsWith(String propertyName, String value) {
173    return DB.getExpressionFactory().istartsWith(propertyName, value);
174  }
175
176  /**
177   * Ends With - property like %value.
178   */
179  public static Expression endsWith(String propertyName, String value) {
180    return DB.getExpressionFactory().endsWith(propertyName, value);
181  }
182
183  /**
184   * Case insensitive Ends With - property like %value. Typically uses a lower()
185   * function to make the expression case insensitive.
186   */
187  public static Expression iendsWith(String propertyName, String value) {
188    return DB.getExpressionFactory().iendsWith(propertyName, value);
189  }
190
191  /**
192   * Contains - property like %value%.
193   */
194  public static Expression contains(String propertyName, String value) {
195    return DB.getExpressionFactory().contains(propertyName, value);
196  }
197
198  /**
199   * Case insensitive Contains - property like %value%. Typically uses a lower()
200   * function to make the expression case insensitive.
201   */
202  public static Expression icontains(String propertyName, String value) {
203    return DB.getExpressionFactory().icontains(propertyName, value);
204  }
205
206  /**
207   * For collection properties that are empty (have not existing elements).
208   */
209  public static Expression isEmpty(String propertyName) {
210    return DB.getExpressionFactory().isEmpty(propertyName);
211  }
212
213  /**
214   * For collection properties that are not empty (have existing elements).
215   */
216  public static Expression isNotEmpty(String propertyName) {
217    return DB.getExpressionFactory().isNotEmpty(propertyName);
218  }
219
220  /**
221   * In - property has a value in the array of values.
222   */
223  public static Expression in(String propertyName, Object[] values) {
224    return DB.getExpressionFactory().in(propertyName, values);
225  }
226
227  /**
228   * In - using a subQuery.
229   */
230  public static Expression in(String propertyName, Query<?> subQuery) {
231    return DB.getExpressionFactory().in(propertyName, subQuery);
232  }
233
234  /**
235   * In - property has a value in the collection of values.
236   */
237  public static Expression in(String propertyName, Collection<?> values) {
238    return DB.getExpressionFactory().in(propertyName, values);
239  }
240
241  /**
242   * In where null or empty values means that no predicate is added to the query.
243   * <p>
244   * That is, only add the IN predicate if the values are not null or empty.
245   * <p>
246   * Without this we typically need to code an <code>if</code> block to only add
247   * the IN predicate if the collection is not empty like:
248   * </p>
249   *
250   * <h3>Without inOrEmpty()</h3>
251   * <pre>{@code
252   *
253   *   query.where() // add some predicates
254   *     .eq("status", Status.NEW);
255   *
256   *   if (ids != null && !ids.isEmpty()) {
257   *     query.where().in("customer.id", ids);
258   *   }
259   *
260   *   query.findList();
261   *
262   * }</pre>
263   *
264   * <h3>Using inOrEmpty()</h3>
265   * <pre>{@code
266   *
267   *   query.where()
268   *     .eq("status", Status.NEW)
269   *     .inOrEmpty("customer.id", ids)
270   *     .findList();
271   *
272   * }</pre>
273   */
274  public static Expression inOrEmpty(String propertyName, Collection<?> values) {
275    return DB.getExpressionFactory().inOrEmpty(propertyName, values);
276  }
277
278  /**
279   * Id Equal to - ID property is equal to the value.
280   */
281  public static Expression idEq(Object value) {
282    return DB.getExpressionFactory().idEq(value);
283  }
284
285  /**
286   * All Equal - Map containing property names and their values.
287   * <p>
288   * Expression where all the property names in the map are equal to the
289   * corresponding value.
290   * </p>
291   *
292   * @param propertyMap a map keyed by property names.
293   */
294  public static Expression allEq(Map<String, Object> propertyMap) {
295    return DB.getExpressionFactory().allEq(propertyMap);
296  }
297
298  /**
299   * Add raw expression with a single parameter.
300   * <p>
301   * The raw expression should contain a single ? at the location of the
302   * parameter.
303   * </p>
304   */
305  public static Expression raw(String raw, Object value) {
306    return DB.getExpressionFactory().raw(raw, value);
307  }
308
309  /**
310   * Add raw expression with an array of parameters.
311   * <p>
312   * The raw expression should contain the same number of ? as there are
313   * parameters.
314   * </p>
315   */
316  public static Expression raw(String raw, Object[] values) {
317    return DB.getExpressionFactory().raw(raw, values);
318  }
319
320  /**
321   * Add raw expression with no parameters.
322   */
323  public static Expression raw(String raw) {
324    return DB.getExpressionFactory().raw(raw);
325  }
326
327  /**
328   * And - join two expressions with a logical and.
329   */
330  public static Expression and(Expression expOne, Expression expTwo) {
331
332    return DB.getExpressionFactory().and(expOne, expTwo);
333  }
334
335  /**
336   * Or - join two expressions with a logical or.
337   */
338  public static Expression or(Expression expOne, Expression expTwo) {
339
340    return DB.getExpressionFactory().or(expOne, expTwo);
341  }
342
343  /**
344   * Negate the expression (prefix it with NOT).
345   */
346  public static Expression not(Expression exp) {
347
348    return DB.getExpressionFactory().not(exp);
349  }
350
351  /**
352   * Return a list of expressions that will be joined by AND's.
353   */
354  public static <T> Junction<T> conjunction(Query<T> query) {
355
356    return DB.getExpressionFactory().conjunction(query);
357  }
358
359  /**
360   * Return a list of expressions that will be joined by OR's.
361   */
362  public static <T> Junction<T> disjunction(Query<T> query) {
363
364    return DB.getExpressionFactory().disjunction(query);
365  }
366}