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