com.avaje.ebean

Interface ExpressionList<T>

All Superinterfaces:

Serializable

All Known Subinterfaces:

Junction<T>

public interface ExpressionList<T>
extends Serializable

List of Expressions that make up a where or having clause.

An ExpressionList is returned from Query.where().

The ExpressionList has a list of convenience methods that create the standard expressions and add them to this list.

The ExpressionList also duplicates methods that are found on the Query such as findList() and orderBy(). The purpose of these methods is provide a fluid API. The upside of this approach is that you can build and execute a query via chained methods. The down side is that this ExpressionList object has more methods than you would initially expect (the ones duplicated from Query).

See Also:

Query.where()

Method Summary

Modifier and Type	Method and Description
ExpressionList<T>	add(Expression expr) Add an Expression to the list.
ExpressionList<T>	addAll(ExpressionList<T> exprList) Add a list of Expressions to this ExpressionList.s
ExpressionList<T>	allEq(Map<String,Object> propertyMap) All Equal - Map containing property names and their values.
ExpressionList<T>	and(Expression expOne, Expression expTwo) And - join two expressions with a logical and.
Query<T>	apply(PathProperties pathProperties) Apply the path properties to the query replacing the select and fetch clauses.
Query<T>	asOf(Timestamp asOf) Perform an 'As of' query using history tables to return the object graph as of a time in the past.
ExpressionList<T>	between(String propertyName, Object value1, Object value2) Between - property between the two given values.
ExpressionList<T>	betweenProperties(String lowProperty, String highProperty, Object value) Between - value between the two properties.
Junction<T>	conjunction() Return a list of expressions that will be joined by AND's.
ExpressionList<T>	contains(String propertyName, String value) Contains - property like %value%.
int	delete() Execute as a delete query deleting the 'root level' beans that match the predicates in the query.
Junction<T>	disjunction() Return a list of expressions that will be joined by OR's.
ExpressionList<T>	endJunction() End a Conjunction or Disjunction returning the parent expression list.
ExpressionList<T>	endsWith(String propertyName, String value) Ends With - property like %value.
ExpressionList<T>	eq(String propertyName, Object value) Equal To - property is equal to a given value.
ExpressionList<T>	exampleLike(Object example) A "Query By Example" type of expression.
ExpressionList<T>	exists(Query<?> subQuery) Exists expression
ExpressionList<T>	filterMany(String prop) Add some filter predicate expressions to the many property.
void	findEach(QueryEachConsumer<T> consumer) Execute the query process the beans one at a time.
void	findEachWhile(QueryEachWhileConsumer<T> consumer) Execute the query processing the beans one at a time with the ability to stop processing before reading all the beans.
FutureIds<T>	findFutureIds() Execute find Id's query in a background thread.
FutureList<T>	findFutureList() Execute find list query in a background thread.
FutureRowCount<T>	findFutureRowCount() Execute find row count query in a background thread.
List<Object>	findIds() Execute the query returning the list of Id's.
QueryIterator<T>	findIterate() Execute the query iterating over the results.
List<T>	findList() Execute the query returning a list.
Map<?,T>	findMap() Execute the query returning a map.
<K> Map<K,T>	findMap(String keyProperty, Class<K> keyType) Return a typed map specifying the key property and type.
PagedList<T>	findPagedList(int pageIndex, int pageSize) Return a PagedList for this query.
int	findRowCount() Return the count of entities this query should return.
Set<T>	findSet() Execute the query returning a set.
T	findUnique() Execute the query returning a single bean.
List<Version<T>>	findVersions() Return versions of a @History entity bean.
List<Version<T>>	findVersionsBetween(Timestamp start, Timestamp end) Return versions of a @History entity bean between the 2 timestamps.
ExpressionList<T>	ge(String propertyName, Object value) Greater Than or Equal to - property greater than or equal to the given value.
ExpressionList<T>	gt(String propertyName, Object value) Greater Than - property greater than the given value.
ExpressionList<T>	having() Add expressions to the having clause.
ExpressionList<T>	icontains(String propertyName, String value) Case insensitive Contains - property like %value%.
ExpressionList<T>	idEq(Object value) Id Equal to - ID property is equal to the value.
ExpressionList<T>	idIn(List<?> idValues) Id IN a list of id values.
ExpressionList<T>	iendsWith(String propertyName, String value) Case insensitive Ends With - property like %value.
ExpressionList<T>	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).
ExpressionList<T>	iexampleLike(Object example) Case insensitive version of exampleLike(Object)
ExpressionList<T>	ilike(String propertyName, String value) Case insensitive Like - property like value where the value contains the SQL wild card characters % (percentage) and _ (underscore).
ExpressionList<T>	in(String propertyName, Collection<?> values) In - property has a value in the collection of values.
ExpressionList<T>	in(String propertyName, Object... values) In - property has a value in the array of values.
ExpressionList<T>	in(String propertyName, Query<?> subQuery) In - using a subQuery.
ExpressionList<T>	isNotNull(String propertyName) Is Not Null - property is not null.
ExpressionList<T>	isNull(String propertyName) Is Null - property is null.
ExpressionList<T>	istartsWith(String propertyName, String value) Case insensitive Starts With - property like value%.
ExpressionList<T>	jsonBetween(String propertyName, String path, Object lowerValue, Object upperValue) Between - for the given path in a JSON document.
ExpressionList<T>	jsonEqualTo(String propertyName, String path, Object value) Equal to expression for the value at the given path in the JSON document.
ExpressionList<T>	jsonExists(String propertyName, String path) Path exists - for the given path in a JSON document.
ExpressionList<T>	jsonGreaterOrEqual(String propertyName, String path, Object value) Greater than or equal to - for the given path in a JSON document.
ExpressionList<T>	jsonGreaterThan(String propertyName, String path, Object value) Greater than - for the given path in a JSON document.
ExpressionList<T>	jsonLessOrEqualTo(String propertyName, String path, Object value) Less than or equal to - for the given path in a JSON document.
ExpressionList<T>	jsonLessThan(String propertyName, String path, Object value) Less than - for the given path in a JSON document.
ExpressionList<T>	jsonNotEqualTo(String propertyName, String path, Object value) Not Equal to - for the given path in a JSON document.
ExpressionList<T>	jsonNotExists(String propertyName, String path) Path does not exist - for the given path in a JSON document.
ExpressionList<T>	le(String propertyName, Object value) Less Than or Equal to - property less than or equal to the given value.
ExpressionList<T>	like(String propertyName, String value) Like - property like value where the value contains the SQL wild card characters % (percentage) and _ (underscore).
ExpressionList<T>	lt(String propertyName, Object value) Less Than - property less than the given value.
ExpressionList<T>	ne(String propertyName, Object value) Not Equal To - property not equal to the given value.
ExpressionList<T>	not(Expression exp) Negate the expression (prefix it with NOT).
ExpressionList<T>	notExists(Query<?> subQuery) Not exists expression
ExpressionList<T>	notIn(String propertyName, Collection<?> values) Not In - property has a value in the collection of values.
ExpressionList<T>	notIn(String propertyName, Object... values) Not In - property has a value in the array of values.
ExpressionList<T>	notIn(String propertyName, Query<?> subQuery) Not In - using a subQuery.
ExpressionList<T>	or(Expression expOne, Expression expTwo) Or - join two expressions with a logical or.
OrderBy<T>	order() Return the OrderBy so that you can append an ascending or descending property to the order by clause.
Query<T>	order(String orderByClause) Set the order by clause replacing the existing order by clause if there is one.
OrderBy<T>	orderBy() Return the OrderBy so that you can append an ascending or descending property to the order by clause.
Query<T>	orderBy(String orderBy) Add an orderBy clause to the query.
Query<T>	query() Return the query that owns this expression list.
ExpressionList<T>	raw(String raw) Add raw expression with no parameters.
ExpressionList<T>	raw(String raw, Object value) Add raw expression with a single parameter.
ExpressionList<T>	raw(String raw, Object[] values) Add raw expression with an array of parameters.
Query<T>	select(String properties) Specify specific properties to fetch on the main/root bean (aka partial object).
Query<T>	setDistinct(boolean distinct) Set whether this query uses DISTINCT.
Query<T>	setFirstRow(int firstRow) Set the first row to fetch.
Query<T>	setMapKey(String mapKey) Set the name of the property which values become the key of a map.
Query<T>	setMaxRows(int maxRows) Set the maximum number of rows to fetch.
Query<T>	setOrderBy(String orderBy) Add an orderBy clause to the query.
Query<T>	setUseCache(boolean useCache) Set to true to use the query for executing this query.
Query<T>	setUseQueryCache(boolean useCache) Set to true to use the query for executing this query.
ExpressionList<T>	startsWith(String propertyName, String value) Starts With - property like value%.
ExpressionList<T>	where() Add another expression to the where clause.

Method Detail

query

Query<T> query()

Return the query that owns this expression list.

This is a convenience method solely to support a fluid API where the methods are chained together. Adding expressions returns this expression list and this method can be used after that to return back the original query so that further things can be added to it.

order

Query<T> order(String orderByClause)

Set the order by clause replacing the existing order by clause if there is one.

This follows SQL syntax using commas between each property with the optional asc and desc keywords representing ascending and descending order respectively.

This is EXACTLY the same as orderBy(String).

order

OrderBy<T> order()

Return the OrderBy so that you can append an ascending or descending property to the order by clause.

This will never return a null. If no order by clause exists then an 'empty' OrderBy object is returned.

orderBy

OrderBy<T> orderBy()

Return the OrderBy so that you can append an ascending or descending property to the order by clause.

This will never return a null. If no order by clause exists then an 'empty' OrderBy object is returned.

orderBy

Query<T> orderBy(String orderBy)

Add an orderBy clause to the query.

See Also:

Query.orderBy(String)

setOrderBy

Query<T> setOrderBy(String orderBy)

Add an orderBy clause to the query.

See Also:

Query.orderBy(String)

apply

Query<T> apply(PathProperties pathProperties)

Apply the path properties to the query replacing the select and fetch clauses.

asOf

Query<T> asOf(Timestamp asOf)

Perform an 'As of' query using history tables to return the object graph as of a time in the past.

To perform this query the DB must have underlying history tables.

Parameters:

asOf - the date time in the past at which you want to view the data

delete

int delete()

Execute as a delete query deleting the 'root level' beans that match the predicates in the query.

Note that if the query includes joins then the generated delete statement may not be optimal depending on the database platform.

Returns:

the number of beans/rows that were deleted.

findIterate

QueryIterator<T> findIterate()

Execute the query iterating over the results.

See Also:

Query.findIterate()

findEach

void findEach(QueryEachConsumer<T> consumer)

Execute the query process the beans one at a time.

See Also:

Query.findEach(QueryEachConsumer)

findEachWhile

void findEachWhile(QueryEachWhileConsumer<T> consumer)

Execute the query processing the beans one at a time with the ability to stop processing before reading all the beans.

See Also:

Query.findEachWhile(QueryEachWhileConsumer)

findList

List<T> findList()

Execute the query returning a list.

See Also:

Query.findList()

findIds

List<Object> findIds()

Execute the query returning the list of Id's.

See Also:

Query.findIds()

findRowCount

int findRowCount()

Return the count of entities this query should return.

This is the number of 'top level' or 'root level' entities.

findSet

Set<T> findSet()

Execute the query returning a set.

See Also:

Query.findSet()

findMap

Map<?,T> findMap()

Execute the query returning a map.

See Also:

Query.findMap()

findMap

<K> Map<K,T> findMap(String keyProperty,
                     Class<K> keyType)

Return a typed map specifying the key property and type.

findUnique

@Nullable
T findUnique()

Execute the query returning a single bean.

See Also:

Query.findUnique()

findFutureRowCount

FutureRowCount<T> findFutureRowCount()

Execute find row count query in a background thread.

This returns a Future object which can be used to cancel, check the execution status (isDone etc) and get the value (with or without a timeout).

Returns:

a Future object for the row count query

findFutureIds

FutureIds<T> findFutureIds()

Execute find Id's query in a background thread.

This returns a Future object which can be used to cancel, check the execution status (isDone etc) and get the value (with or without a timeout).

Returns:

a Future object for the list of Id's

findFutureList

FutureList<T> findFutureList()

Execute find list query in a background thread.

This returns a Future object which can be used to cancel, check the execution status (isDone etc) and get the value (with or without a timeout).

Returns:

a Future object for the list result of the query

findPagedList

PagedList<T> findPagedList(int pageIndex,
                           int pageSize)

Return a PagedList for this query.

The benefit of using this over just using the normal Query.setFirstRow(int) and Query.setMaxRows(int) is that it additionally wraps an optional call to Query.findFutureRowCount() to determine total row count, total page count etc.

Internally this works using Query.setFirstRow(int) and Query.setMaxRows(int) on the query. This translates into SQL that uses limit offset, rownum or row_number function to limit the result set.

Parameters:

pageIndex - The zero based index of the page.

pageSize - The number of beans to return per page.

Returns:

The PagedList

findVersions

List<Version<T>> findVersions()

Return versions of a @History entity bean.

Generally this query is expected to be a find by id or unique predicates query. It will execute the query against the history returning the versions of the bean.

findVersionsBetween

List<Version<T>> findVersionsBetween(Timestamp start,
                                     Timestamp end)

Return versions of a @History entity bean between the 2 timestamps.

Generally this query is expected to be a find by id or unique predicates query. It will execute the query against the history returning the versions of the bean.

filterMany

ExpressionList<T> filterMany(String prop)

Add some filter predicate expressions to the many property.

select

Query<T> select(String properties)

Specify specific properties to fetch on the main/root bean (aka partial object).

See Also:

Query.select(String)

setDistinct

Query<T> setDistinct(boolean distinct)

Set whether this query uses DISTINCT.

The select() clause MUST be specified when setDistinct(true) is set. The reason for this is that generally ORM queries include the "id" property and this doesn't make sense for distinct queries.

  List<Customer> customers =
      Ebean.find(Customer.class)
         .setDistinct(true)
         .select("name")     // only select the customer name
         .findList();

setFirstRow

Query<T> setFirstRow(int firstRow)

Set the first row to fetch.

See Also:

Query.setFirstRow(int)

setMaxRows

Query<T> setMaxRows(int maxRows)

Set the maximum number of rows to fetch.

See Also:

Query.setMaxRows(int)

setMapKey

Query<T> setMapKey(String mapKey)

Set the name of the property which values become the key of a map.

See Also:

Query.setMapKey(String)

setUseCache

Query<T> setUseCache(boolean useCache)

Set to true to use the query for executing this query.

See Also:

Query.setUseCache(boolean)

setUseQueryCache

Query<T> setUseQueryCache(boolean useCache)

Set to true to use the query for executing this query.

See Also:

Query.setUseQueryCache(boolean)

having

ExpressionList<T> having()

Add expressions to the having clause.

The having clause is only used for queries based on raw sql (via SqlSelect annotation etc).

where

ExpressionList<T> where()

Add another expression to the where clause.

jsonExists

ExpressionList<T> jsonExists(String propertyName,
                             String path)

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

  where().jsonExists("content", "path.other")

Parameters:

propertyName - the property that holds a JSON document

path - the nested path in the JSON document in dot notation

jsonNotExists

ExpressionList<T> jsonNotExists(String propertyName,
                                String path)

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

  where().jsonNotExists("content", "path.other")

Parameters:

propertyName - the property that holds a JSON document

path - the nested path in the JSON document in dot notation

jsonEqualTo

ExpressionList<T> jsonEqualTo(String propertyName,
                              String path,
                              Object value)

Equal to expression for the value at the given path in the JSON document.

  where().jsonEqualTo("content", "path.other", 34)

Parameters:

propertyName - the property that holds a JSON document

path - the nested path in the JSON document in dot notation

value - the value used to test against the document path's value

jsonNotEqualTo

ExpressionList<T> jsonNotEqualTo(String propertyName,
                                 String path,
                                 Object value)

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

  where().jsonNotEqualTo("content", "path.other", 34)

Parameters:

propertyName - the property that holds a JSON document

path - the nested path in the JSON document in dot notation

value - the value used to test against the document path's value

jsonGreaterThan

ExpressionList<T> jsonGreaterThan(String propertyName,
                                  String path,
                                  Object value)

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

  where().jsonGreaterThan("content", "path.other", 34)

jsonGreaterOrEqual

ExpressionList<T> jsonGreaterOrEqual(String propertyName,
                                     String path,
                                     Object value)

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

  where().jsonGreaterOrEqual("content", "path.other", 34)

jsonLessThan

ExpressionList<T> jsonLessThan(String propertyName,
                               String path,
                               Object value)

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

  where().jsonLessThan("content", "path.other", 34)

jsonLessOrEqualTo

ExpressionList<T> jsonLessOrEqualTo(String propertyName,
                                    String path,
                                    Object value)

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

  where().jsonLessOrEqualTo("content", "path.other", 34)

jsonBetween

ExpressionList<T> jsonBetween(String propertyName,
                              String path,
                              Object lowerValue,
                              Object upperValue)

Between - for the given path in a JSON document.

  where().jsonBetween("content", "orderDate", lowerDateTime, upperDateTime)

add

ExpressionList<T> add(Expression expr)

Add an Expression to the list.

This returns the list so that add() can be chained.

Query<Customer> query = Ebean.find(Customer.class);
query.where()
    .like("name","Rob%")
    .eq("status", Customer.ACTIVE);

List<Customer> list = query.findList();
...

addAll

ExpressionList<T> addAll(ExpressionList<T> exprList)

Add a list of Expressions to this ExpressionList.s

eq

ExpressionList<T> eq(String propertyName,
                     Object value)

Equal To - property is equal to a given value.

ne

ExpressionList<T> ne(String propertyName,
                     Object value)

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

ieq

ExpressionList<T> 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).

between

ExpressionList<T> between(String propertyName,
                          Object value1,
                          Object value2)

Between - property between the two given values.

betweenProperties

ExpressionList<T> betweenProperties(String lowProperty,
                                    String highProperty,
                                    Object value)

Between - value between the two properties.

gt

ExpressionList<T> gt(String propertyName,
                     Object value)

Greater Than - property greater than the given value.

ge

ExpressionList<T> ge(String propertyName,
                     Object value)

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

lt

ExpressionList<T> lt(String propertyName,
                     Object value)

Less Than - property less than the given value.

le

ExpressionList<T> le(String propertyName,
                     Object value)

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

isNull

ExpressionList<T> isNull(String propertyName)

Is Null - property is null.

isNotNull

ExpressionList<T> isNotNull(String propertyName)

Is Not Null - property is not null.

exampleLike

ExpressionList<T> exampleLike(Object example)

A "Query By Example" type of expression.

Pass in an example entity and for each non-null scalar properties an expression is added.

By Default this case sensitive, will ignore numeric zero values and will use a Like for string values (you must put in your own wildcards).

To get control over the options you can create an ExampleExpression and set those options such as case insensitive etc.

// create an example bean and set the properties
// with the query parameters you want
Customer example = new Customer();
example.setName("Rob%");
example.setNotes("%something%");

List<Customer> list = Ebean.find(Customer.class).where()
    // pass the bean into the where() clause
    .exampleLike(example)
    // you can add other expressions to the same query
    .gt("id", 2).findList();

Similarly you can create an ExampleExpression

Customer example = new Customer();
example.setName("Rob%");
example.setNotes("%something%");

// create a ExampleExpression with more control
ExampleExpression qbe = new ExampleExpression(example, true, LikeType.EQUAL_TO).includeZeros();

List<Customer> list = Ebean.find(Customer.class).where().add(qbe).findList();

iexampleLike

ExpressionList<T> iexampleLike(Object example)

Case insensitive version of exampleLike(Object)

like

ExpressionList<T> like(String propertyName,
                       String value)

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

ilike

ExpressionList<T> 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

ExpressionList<T> startsWith(String propertyName,
                             String value)

Starts With - property like value%.

istartsWith

ExpressionList<T> istartsWith(String propertyName,
                              String value)

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

endsWith

ExpressionList<T> endsWith(String propertyName,
                           String value)

Ends With - property like %value.

iendsWith

ExpressionList<T> iendsWith(String propertyName,
                            String value)

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

contains

ExpressionList<T> contains(String propertyName,
                           String value)

Contains - property like %value%.

icontains

ExpressionList<T> icontains(String propertyName,
                            String value)

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

in

ExpressionList<T> in(String propertyName,
                     Query<?> subQuery)

In - using a subQuery.

in

ExpressionList<T> in(String propertyName,
                     Object... values)

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

in

ExpressionList<T> in(String propertyName,
                     Collection<?> values)

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

notIn

ExpressionList<T> notIn(String propertyName,
                        Object... values)

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

notIn

ExpressionList<T> notIn(String propertyName,
                        Collection<?> values)

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

notIn

ExpressionList<T> notIn(String propertyName,
                        Query<?> subQuery)

Not In - using a subQuery.

exists

ExpressionList<T> exists(Query<?> subQuery)

Exists expression

notExists

ExpressionList<T> notExists(Query<?> subQuery)

Not exists expression

idIn

ExpressionList<T> idIn(List<?> idValues)

Id IN a list of id values.

idEq

ExpressionList<T> idEq(Object value)

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

allEq

ExpressionList<T> 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.

raw

ExpressionList<T> 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.

When properties in the clause are fully qualified as table-column names then they are not translated. logical property name names (not fully qualified) will still be translated to their physical name.

Example:

  // use a database function
  raw("add_days(orderDate, 10) < ?", someDate)

raw

ExpressionList<T> 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.

When properties in the clause are fully qualified as table-column names then they are not translated. logical property name names (not fully qualified) will still be translated to their physical name.

raw

ExpressionList<T> raw(String raw)

Add raw expression with no parameters.

When properties in the clause are fully qualified as table-column names then they are not translated. logical property name names (not fully qualified) will still be translated to their physical name.

  raw("orderQty < shipQty")

and

ExpressionList<T> and(Expression expOne,
                      Expression expTwo)

And - join two expressions with a logical and.

or

ExpressionList<T> or(Expression expOne,
                     Expression expTwo)

Or - join two expressions with a logical or.

not

ExpressionList<T> not(Expression exp)

Negate the expression (prefix it with NOT).

conjunction

Junction<T> conjunction()

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

disjunction

Junction<T> disjunction()

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

endJunction

ExpressionList<T> endJunction()

End a Conjunction or Disjunction returning the parent expression list.

Alternatively you can always use where() to return the top level expression list.