Package io.ebean

Interface ExpressionFactory

public interface ExpressionFactory

Expression factory for creating standard expressions.

Creates standard common expressions for using in a Query Where or Having clause.

You will often not use this class directly but instead just add expressions via the methods on ExpressionList such as ExpressionList.gt(String, Object).

The ExpressionList is returned from Query.where().

 // Example: fetch orders where status equals new or orderDate > lastWeek.

 Expression newOrLastWeek =
     Expr.or(Expr.eq("status", Order.Status.NEW),
             Expr.gt("orderDate", lastWeek));

 List<Order> list = DB.find(Order.class)
   .where().add(newOrLastWeek)
   .findList();
 ...
 

See Also:

Query.where()

Method Summary

Modifier and Type	Method	Description
Expression	allEq(Map<String,Object> propertyMap)	All Equal - Map containing property names and their values.
Expression	and(Expression expOne, Expression expTwo)	And - join two expressions with a logical and.
Expression	arrayContains(String propertyName, Object... values)	Array contains all the given values.
Expression	arrayIsEmpty(String propertyName)	Array is empty - for the given array property.
Expression	arrayIsNotEmpty(String propertyName)	Array is not empty - for the given array property.
Expression	arrayNotContains(String propertyName, Object... values)	Array does not contain the given values.
Expression	between(String propertyName, Object value1, Object value2)	Between - property between the two given values.
Expression	betweenProperties(String lowProperty, String highProperty, Object value)	Between - value between two given properties.
Expression	bitwiseAll(String propertyName, long flags)	Add expression for ALL of the given bit flags to be set.
Expression	bitwiseAnd(String propertyName, long flags, long match)	Add bitwise AND expression of the given bit flags to compare with the match/mask.
Expression	bitwiseAny(String propertyName, long flags)	Add expression for ANY of the given bit flags to be set.
<T> Junction<T>	conjunction(Query<T> query)	Return a list of expressions that will be joined by AND's.
<T> Junction<T>	conjunction(Query<T> query, ExpressionList<T> parent)	Return a list of expressions that will be joined by AND's.
Expression	contains(String propertyName, String value)	Contains - property like %value%.
<T> Junction<T>	disjunction(Query<T> query)	Return a list of expressions that will be joined by OR's.
<T> Junction<T>	disjunction(Query<T> query, ExpressionList<T> parent)	Return a list of expressions that will be joined by OR's.
Expression	endsWith(String propertyName, String value)	Ends With - property like %value.
Expression	eq(String propertyName, Object value)	Equal To - property equal to the given value.
Expression	eqOrNull(String propertyName, Object value)	Equal To or Null - property equal to the given value or null.
ExampleExpression	exampleLike(Object example)	Create the query by Example expression which is case sensitive and using LikeType.RAW (you need to add you own wildcards % and _).
ExampleExpression	exampleLike(Object example, boolean caseInsensitive, LikeType likeType)	Create the query by Example expression specifying more options.
Expression	exists(Query<?> subQuery)	Exists expression
Expression	ge(String propertyName, Object value)	Greater Than or Equal to - property greater than or equal to the given value.
Expression	gt(String propertyName, Object value)	Greater Than - property greater than the given value.
Expression	gtOrNull(String propertyName, Object value)	Greater Than Or Null - property greater than the given value or null.
Expression	icontains(String propertyName, String value)	Case insensitive Contains - property like %value%.
Expression	idEq(Object value)	Id Equal to - ID property is equal to the value.
Expression	idIn(Object... idValues)	Id IN a list of Id values.
Expression	idIn(Collection<?> idCollection)	Id IN a collection of Id values.
Expression	iendsWith(String propertyName, String value)	Case insensitive Ends With - property like %value.
Expression	ieq(String propertyName, String value)	Case Insensitive Equal To - property equal to the given value (typically using a lower() function to make it case insensitive).
Expression	ieqObject(String propertyName, Object value)	Case Insensitive Equal To that allows for named parameter use.
ExampleExpression	iexampleLike(Object example)	Case insensitive exampleLike(Object)
Expression	ilike(String propertyName, String value)	Case insensitive Like - property like value where the value contains the SQL wild card characters % (percentage) and _ (underscore).
Expression	in(String propertyName, Query<?> subQuery)	In - using a subQuery.
Expression	in(String propertyName, Object[] values)	In - property has a value in the array of values.
Expression	in(String propertyName, Collection<?> values)	In - property has a value in the collection of values.
Expression	ine(String propertyName, String value)	Case Insensitive Not Equal To - property not equal to the given value (typically using a lower() function to make it case insensitive).
Expression	ineObject(String propertyName, Object value)	Case Insensitive Not Equal To that allows for named parameter use.
Expression	inOrEmpty(String propertyName, Collection<?> values)	In where null or empty values means that no predicate is added to the query.
Expression	inPairs(Pairs pairs)	In expression using pairs of value objects.
Expression	inRange(String propertyName, Object value1, Object value2)	In Range - property >= value1 and property < value2.
Expression	inRangeWith(String lowProperty, String highProperty, Object value)	Value in Range between 2 properties.
Expression	isEmpty(String propertyName)	Is empty expression for collection properties.
Expression	isNotEmpty(String propertyName)	Is not empty expression for collection properties.
Expression	isNotNull(String propertyName)	Is Not Null - property is not null.
Expression	isNull(String propertyName)	Is Null - property is null.
Expression	istartsWith(String propertyName, String value)	Case insensitive Starts With - property like value%.
Expression	jsonBetween(String propertyName, String path, Object lowerValue, Object upperValue)	Between - for the given path in a JSON document.
Expression	jsonEqualTo(String propertyName, String path, Object val)	Equal to - for the given path in a JSON document.
Expression	jsonExists(String propertyName, String path)	Path exists - for the given path in a JSON document.
Expression	jsonGreaterOrEqual(String propertyName, String path, Object val)	Greater than or equal to - for the given path in a JSON document.
Expression	jsonGreaterThan(String propertyName, String path, Object val)	Greater than - for the given path in a JSON document.
Expression	jsonLessOrEqualTo(String propertyName, String path, Object val)	Less than or equal to - for the given path in a JSON document.
Expression	jsonLessThan(String propertyName, String path, Object val)	Less than - for the given path in a JSON document.
Expression	jsonNotEqualTo(String propertyName, String path, Object val)	Not Equal to - for the given path in a JSON document.
Expression	jsonNotExists(String propertyName, String path)	Path does not exist - for the given path in a JSON document.
<T> Junction<T>	junction(Junction.Type type, Query<T> query, ExpressionList<T> parent)	Return a Text query junction for MUST, SHOULD or MUST NOT.
Expression	le(String propertyName, Object value)	Less Than or Equal to - property less than or equal to the given value.
Expression	like(String propertyName, Object value, boolean caseInsensitive, LikeType likeType)	Like with support for named parameters.
Expression	like(String propertyName, String value)	Like - property like value where the value contains the SQL wild card characters % (percentage) and _ (underscore).
Expression	lt(String propertyName, Object value)	Less Than - property less than the given value.
Expression	ltOrNull(String propertyName, Object value)	Less Than or Null - property less than the given value or null.
Expression	ne(String propertyName, Object value)	Not Equal To - property not equal to the given value.
Expression	not(Expression exp)	Negate the expression (prefix it with NOT).
Expression	notExists(Query<?> subQuery)	Not exists expression
Expression	notIn(String propertyName, Query<?> subQuery)	Not In - using a subQuery.
Expression	notIn(String propertyName, Object[] values)	Not In - property has a value in the array of values.
Expression	notIn(String propertyName, Collection<?> values)	Not In - property has a value in the collection of values.
Expression	or(Expression expOne, Expression expTwo)	Or - join two expressions with a logical or.
Expression	raw(String raw)	Add raw expression with no parameters.
Expression	raw(String raw, Object value)	Add raw expression with a single parameter.
Expression	raw(String raw, Object[] values)	Add raw expression with an array of parameters.
Expression	startsWith(String propertyName, String value)	Starts With - property like value%.
Expression	textCommonTerms(String search, TextCommonTerms options)	Create a text common terms expression (currently doc store/Elastic only).
Expression	textMatch(String propertyName, String search, Match options)	Create a Text Match expression (currently doc store/Elastic only).
Expression	textMultiMatch(String query, MultiMatch options)	Create a Text Multi match expression (currently doc store/Elastic only).
Expression	textQueryString(String search, TextQueryString options)	Create a text query string expression (currently doc store/Elastic only).
Expression	textSimple(String search, TextSimple options)	Create a text simple query expression (currently doc store/Elastic only).
<T> void	where(ExpressionList<T> where, String expressions, Object[] params)	Add the expressions to the given expression list.

Method Detail

jsonExists

Expression jsonExists(String propertyName,
                      String path)

Path exists - for the given path in a JSON document.

jsonNotExists

Expression jsonNotExists(String propertyName,
                         String path)

Path does not exist - for the given path in a JSON document.

jsonEqualTo

Expression jsonEqualTo(String propertyName,
                       String path,
                       Object val)

Equal to - for the given path in a JSON document.

jsonNotEqualTo

Expression jsonNotEqualTo(String propertyName,
                          String path,
                          Object val)

Not Equal to - for the given path in a JSON document.

jsonGreaterThan

Expression jsonGreaterThan(String propertyName,
                           String path,
                           Object val)

Greater than - for the given path in a JSON document.

jsonGreaterOrEqual

Expression jsonGreaterOrEqual(String propertyName,
                              String path,
                              Object val)

Greater than or equal to - for the given path in a JSON document.

jsonLessThan

Expression jsonLessThan(String propertyName,
                        String path,
                        Object val)

Less than - for the given path in a JSON document.

jsonLessOrEqualTo

Expression jsonLessOrEqualTo(String propertyName,
                             String path,
                             Object val)

Less than or equal to - for the given path in a JSON document.

jsonBetween

Expression jsonBetween(String propertyName,
                       String path,
                       Object lowerValue,
                       Object upperValue)

Between - for the given path in a JSON document.

arrayContains

Expression arrayContains(String propertyName,
                         Object... values)

Array contains all the given values.

Array support is effectively limited to Postgres at this time.

arrayNotContains

Expression arrayNotContains(String propertyName,
                            Object... values)

Array does not contain the given values.

Array support is effectively limited to Postgres at this time.

arrayIsEmpty

Expression arrayIsEmpty(String propertyName)

Array is empty - for the given array property.

Array support is effectively limited to Postgres at this time.

arrayIsNotEmpty

Expression arrayIsNotEmpty(String propertyName)

Array is not empty - for the given array property.

Array support is effectively limited to Postgres at this time.

eq

Expression eq(String propertyName,
              Object value)

Equal To - property equal to the given value.

eqOrNull

Expression eqOrNull(String propertyName,
                    Object value)

Equal To or Null - property equal to the given value or null.

ne

Expression ne(String propertyName,
              Object value)

Not Equal To - property not equal to the given value.

ieq

Expression ieq(String propertyName,
               String value)

Case Insensitive Equal To - property equal to the given value (typically using a lower() function to make it case insensitive).

ine

Expression ine(String propertyName,
               String value)

Case Insensitive Not Equal To - property not equal to the given value (typically using a lower() function to make it case insensitive).

ieqObject

Expression ieqObject(String propertyName,
                     Object value)

Case Insensitive Equal To that allows for named parameter use.

ineObject

Expression ineObject(String propertyName,
                     Object value)

Case Insensitive Not Equal To that allows for named parameter use.

inRange

Expression inRange(String propertyName,
                   Object value1,
                   Object value2)

In Range - property >= value1 and property < value2.

Unlike Between inRange is "half open" and usually more useful for use with dates or timestamps.

inRangeWith

Expression inRangeWith(String lowProperty,
                       String highProperty,
                       Object value)

Value in Range between 2 properties.

    .startDate.inRangeWith(endDate, now)

    // which equates to
    startDate <= now and (endDate > now or endDate is null)

 

This is a convenience expression combining a number of simple expressions. The most common use of this could be called "effective dating" where 2 date or timestamp columns represent the date range in which

between

Expression between(String propertyName,
                   Object value1,
                   Object value2)

Between - property between the two given values.

betweenProperties

Expression betweenProperties(String lowProperty,
                             String highProperty,
                             Object value)

Between - value between two given properties.

gtOrNull

Expression gtOrNull(String propertyName,
                    Object value)

Greater Than Or Null - property greater than the given value or null.

A convenient expression combining GT and Is Null. Most often useful for range expressions where the top range value is nullable.

gt

Expression gt(String propertyName,
              Object value)

Greater Than - property greater than the given value.

ge

Expression ge(String propertyName,
              Object value)

Greater Than or Equal to - property greater than or equal to the given value.

ltOrNull

Expression ltOrNull(String propertyName,
                    Object value)

Less Than or Null - property less than the given value or null.

A convenient expression combining LT and Is Null. Most often useful for range expressions where the bottom range value is nullable.

lt

Expression lt(String propertyName,
              Object value)

Less Than - property less than the given value.

le

Expression le(String propertyName,
              Object value)

Less Than or Equal to - property less than or equal to the given value.

isNull

Expression isNull(String propertyName)

Is Null - property is null.

isNotNull

Expression isNotNull(String propertyName)

Is Not Null - property is not null.

iexampleLike

ExampleExpression iexampleLike(Object example)

Case insensitive exampleLike(Object)

exampleLike

ExampleExpression exampleLike(Object example)

Create the query by Example expression which is case sensitive and using LikeType.RAW (you need to add you own wildcards % and _).

exampleLike

ExampleExpression exampleLike(Object example,
                              boolean caseInsensitive,
                              LikeType likeType)

Create the query by Example expression specifying more options.

like

Expression like(String propertyName,
                Object value,
                boolean caseInsensitive,
                LikeType likeType)

Like with support for named parameters.

like

Expression like(String propertyName,
                String value)

Like - property like value where the value contains the SQL wild card characters % (percentage) and _ (underscore).

ilike

Expression ilike(String propertyName,
                 String value)

Case insensitive Like - property like value where the value contains the SQL wild card characters % (percentage) and _ (underscore). Typically uses a lower() function to make the expression case insensitive.

startsWith

Expression startsWith(String propertyName,
                      String value)

Starts With - property like value%.

istartsWith

Expression istartsWith(String propertyName,
                       String value)

Case insensitive Starts With - property like value%. Typically uses a lower() function to make the expression case insensitive.

endsWith

Expression endsWith(String propertyName,
                    String value)

Ends With - property like %value.

iendsWith

Expression iendsWith(String propertyName,
                     String value)

Case insensitive Ends With - property like %value. Typically uses a lower() function to make the expression case insensitive.

contains

Expression contains(String propertyName,
                    String value)

Contains - property like %value%.

icontains

Expression icontains(String propertyName,
                     String value)

Case insensitive Contains - property like %value%. Typically uses a lower() function to make the expression case insensitive.

inPairs

Expression inPairs(Pairs pairs)

In expression using pairs of value objects.

in

Expression in(String propertyName,
              Object[] values)

In - property has a value in the array of values.

in

Expression in(String propertyName,
              Query<?> subQuery)

In - using a subQuery.

in

Expression in(String propertyName,
              Collection<?> values)

In - property has a value in the collection of values.

inOrEmpty

Expression inOrEmpty(String propertyName,
                     Collection<?> values)

In where null or empty values means that no predicate is added to the query.

That is, only add the IN predicate if the values are not null or empty.

Without this we typically need to code an if block to only add the IN predicate if the collection is not empty like:

Without inOrEmpty()

   query.where() // add some predicates
     .eq("status", Status.NEW);

   if (ids != null && !ids.isEmpty()) {
     query.where().in("customer.id", ids);
   }

   query.findList();

 

Using inOrEmpty()

   query.where()
     .eq("status", Status.NEW)
     .inOrEmpty("customer.id", ids)
     .findList();

 

notIn

Expression notIn(String propertyName,
                 Object[] values)

Not In - property has a value in the array of values.

notIn

Expression notIn(String propertyName,
                 Collection<?> values)

Not In - property has a value in the collection of values.

notIn

Expression notIn(String propertyName,
                 Query<?> subQuery)

Not In - using a subQuery.

exists

Expression exists(Query<?> subQuery)

Exists expression

notExists

Expression notExists(Query<?> subQuery)

Not exists expression

isEmpty

Expression isEmpty(String propertyName)

Is empty expression for collection properties.

isNotEmpty

Expression isNotEmpty(String propertyName)

Is not empty expression for collection properties.

idEq

Expression idEq(Object value)

Id Equal to - ID property is equal to the value.

idIn

Expression idIn(Object... idValues)

Id IN a list of Id values.

idIn

Expression idIn(Collection<?> idCollection)

Id IN a collection of Id values.

allEq

Expression allEq(Map<String,Object> propertyMap)

All Equal - Map containing property names and their values.

Expression where all the property names in the map are equal to the corresponding value.

Parameters:

propertyMap - a map keyed by property names.

bitwiseAny

Expression bitwiseAny(String propertyName,
                      long flags)

Add expression for ANY of the given bit flags to be set.

Parameters:

propertyName - The property that holds the flags value

flags - The flags we are looking for

bitwiseAll

Expression bitwiseAll(String propertyName,
                      long flags)

Add expression for ALL of the given bit flags to be set.

Parameters:

propertyName - The property that holds the flags value

flags - The flags we are looking for

bitwiseAnd

Expression bitwiseAnd(String propertyName,
                      long flags,
                      long match)

Add bitwise AND expression of the given bit flags to compare with the match/mask.

Parameters:

propertyName - The property that holds the flags value

flags - The flags we are looking for

raw

Expression raw(String raw,
               Object value)

Add raw expression with a single parameter.

The raw expression should contain a single ? at the location of the parameter.

raw

Expression raw(String raw,
               Object[] values)

Add raw expression with an array of parameters.

The raw expression should contain the same number of ? as there are parameters.

raw

Expression raw(String raw)

Add raw expression with no parameters.

textMatch

Expression textMatch(String propertyName,
                     String search,
                     Match options)

Create a Text Match expression (currently doc store/Elastic only).

textMultiMatch

Expression textMultiMatch(String query,
                          MultiMatch options)

Create a Text Multi match expression (currently doc store/Elastic only).

textSimple

Expression textSimple(String search,
                      TextSimple options)

Create a text simple query expression (currently doc store/Elastic only).

textQueryString

Expression textQueryString(String search,
                           TextQueryString options)

Create a text query string expression (currently doc store/Elastic only).

textCommonTerms

Expression textCommonTerms(String search,
                           TextCommonTerms options)

Create a text common terms expression (currently doc store/Elastic only).

and

Expression and(Expression expOne,
               Expression expTwo)

And - join two expressions with a logical and.

or

Expression or(Expression expOne,
              Expression expTwo)

Or - join two expressions with a logical or.

not

Expression not(Expression exp)

Negate the expression (prefix it with NOT).

conjunction

<T> Junction<T> conjunction(Query<T> query)

Return a list of expressions that will be joined by AND's.

disjunction

<T> Junction<T> disjunction(Query<T> query)

Return a list of expressions that will be joined by OR's.

conjunction

<T> Junction<T> conjunction(Query<T> query,
                            ExpressionList<T> parent)

Return a list of expressions that will be joined by AND's.

disjunction

<T> Junction<T> disjunction(Query<T> query,
                            ExpressionList<T> parent)

Return a list of expressions that will be joined by OR's.

junction

<T> Junction<T> junction(Junction.Type type,
                         Query<T> query,
                         ExpressionList<T> parent)

Return a Text query junction for MUST, SHOULD or MUST NOT.

This is doc store Elastic only.

where

<T> void where(ExpressionList<T> where,
               String expressions,
               Object[] params)

Add the expressions to the given expression list.

Parameters:

where - The expression list to add the expressions to

expressions - The expressions that are parsed

params - Bind parameters to match ? or ?1 bind positions.