Package io.ebean

Interface ExtendedServer

public interface ExtendedServer

The extended API for Database.

This provides the finder methods that take an explicit transaction rather than obtaining the transaction from the usual mechanism (which is ThreadLocal based).

In general we only want to use this ExtendedServer API when we want to avoid / bypass the use of the mechanism to get the current transaction and instead explicitly supply the transaction to use.

Note that in all cases the transaction supplied can be null and in this case the Database will use the normal mechanism to obtain the transaction to use.

Method Summary

Modifier and Type	Method	Description
long	clockNow()	Return the NOW time from the Clock.
<T> int	delete(Query<T> query, Transaction transaction)	Execute as a delete query deleting the 'root level' beans that match the predicates in the query.
<T> boolean	exists(Query<?> ormQuery, Transaction transaction)	Execute the query returning true if a row is found.
<T> int	findCount(Query<T> query, Transaction transaction)	Return the number of 'top level' or 'root' entities this query should return.
<T> void	findEach(Query<T> query, int batch, Consumer<List<T>> consumer, Transaction t)	Execute findEach with batch consumer.
<T> void	findEach(Query<T> query, Consumer<T> consumer, Transaction transaction)	Execute the query visiting the each bean one at a time.
void	findEach(SqlQuery query, Consumer<SqlRow> consumer, Transaction transaction)	Execute the SqlQuery iterating a row at a time.
<T> void	findEachWhile(Query<T> query, Predicate<T> consumer, Transaction transaction)	Execute the query visiting the each bean one at a time.
void	findEachWhile(SqlQuery query, Predicate<SqlRow> consumer, Transaction transaction)	Execute the SqlQuery iterating a row at a time with the ability to stop consuming part way through.
<T> FutureRowCount<T>	findFutureCount(Query<T> query, Transaction transaction)	Execute find row count query in a background thread.
<T> FutureIds<T>	findFutureIds(Query<T> query, Transaction transaction)	Execute find Id's query in a background thread.
<T> FutureList<T>	findFutureList(Query<T> query, Transaction transaction)	Execute find list query in a background thread returning a FutureList object.
<A,T> List<A>	findIds(Query<T> query, Transaction transaction)	Return the Id values of the query as a List.
<T> QueryIterator<T>	findIterate(Query<T> query, Transaction transaction)	Return a QueryIterator for the query.
<T> Stream<T>	findLargeStream(Query<T> query, Transaction transaction)	Deprecated.
<T> List<T>	findList(Query<T> query, Transaction transaction)	Execute a query returning a list of beans.
List<SqlRow>	findList(SqlQuery query, Transaction transaction)	Execute the sql query returning a list of MapBean.
<K,T> Map<K,T>	findMap(Query<T> query, Transaction transaction)	Execute the query returning the entity beans in a Map.
<T> T	findOne(Query<T> query, Transaction transaction)	Execute the query returning at most one entity bean or null (if no matching bean is found).
SqlRow	findOne(SqlQuery query, Transaction transaction)	Execute the sql query returning a single MapBean or null.
<T> Optional<T>	findOneOrEmpty(Query<T> query, Transaction transaction)	Similar to findOne() but returns an Optional (rather than nullable).
<T> PagedList<T>	findPagedList(Query<T> query, Transaction transaction)	Return a PagedList for this query using firstRow and maxRows.
<T> Set<T>	findSet(Query<T> query, Transaction transaction)	Execute the query returning a set of entity beans.
<A,T> List<A>	findSingleAttributeList(Query<T> query, Transaction transaction)	Execute the query returning a list of values for a single property.
<T> Stream<T>	findStream(Query<T> query, Transaction transaction)	Execute the query returning the result as a Stream.
<T> List<Version<T>>	findVersions(Query<T> query, Transaction transaction)	Return versions of a @History entity bean.
void	setClock(Clock clock)	Set the Clock to use for @WhenCreated and @WhenModified.
<T> int	update(Query<T> query, Transaction transaction)	Execute the update query returning the number of rows updated.

Method Detail

clockNow

long clockNow()

Return the NOW time from the Clock.

setClock

void setClock(Clock clock)

Set the Clock to use for @WhenCreated and @WhenModified.

Note that we only expect to change the Clock for testing purposes.

exists

<T> boolean exists(Query<?> ormQuery,
                   Transaction transaction)

Execute the query returning true if a row is found.

The query is executed using max rows of 1 and will only select the id property. This method is really just a convenient way to optimise a query to perform a 'does a row exist in the db' check.

Example:

   boolean userExists = query().where().eq("email", "rob@foo.com").exists();

 

Example using a query bean:

   boolean userExists = new QContact().email.equalTo("rob@foo.com").exists();

 

Returns:

True if the query finds a matching row in the database

findCount

<T> int findCount(Query<T> query,
                  Transaction transaction)

Return the number of 'top level' or 'root' entities this query should return.

See Also:

Query.findCount(), Query.findFutureCount()

findIds

@Nonnull
<A,T> List<A> findIds(Query<T> query,
                            Transaction transaction)

Return the Id values of the query as a List.

See Also:

Query.findIds()

findIterate

@Nonnull
<T> QueryIterator<T> findIterate(Query<T> query,
                                 Transaction transaction)

Return a QueryIterator for the query.

Generally using findEach(Query, Consumer, Transaction) or findEachWhile(Query, Predicate, Transaction) is preferred to findIterate(). The reason is that those methods automatically take care of closing the queryIterator (and the underlying jdbc statement and resultSet).

This is similar to findEach in that not all the result beans need to be held in memory at the same time and as such is good for processing large queries.

See Also:

Query.findIterate(), Query.findEach(Consumer), Query.findEachWhile(Predicate)

findStream

@Nonnull
<T> Stream<T> findStream(Query<T> query,
                         Transaction transaction)

Execute the query returning the result as a Stream.

Note that this can support very large queries iterating any number of results. To do so internally it can use multiple persistence contexts.

Note that the stream needs to be closed so use with try with resources.

findLargeStream

@Nonnull
@Deprecated
<T> Stream<T> findLargeStream(Query<T> query,
                              Transaction transaction)

Deprecated.

Deprecated - migrate to findStream().

Execute the query returning the result as a Stream.

Note that this can support very large queries iterating any number of results. To do so internally it can use multiple persistence contexts.

Note that the stream needs to be closed so use with try with resources.

findEach

<T> void findEach(Query<T> query,
                  Consumer<T> consumer,
                  Transaction transaction)

Execute the query visiting the each bean one at a time.

Unlike findList() this is suitable for processing a query that will return a very large resultSet. The reason is that not all the result beans need to be held in memory at the same time and instead processed one at a time.

Internally this query using a PersistenceContext scoped to each bean (and the beans associated object graph).

     DB.find(Order.class)
       .where().eq("status", Order.Status.NEW)
       .order().asc("id")
       .findEach((Order order) -> {

         // do something with the order bean
         System.out.println(" -- processing order ... " + order);
       });

 

See Also:

Query.findEach(Consumer), Query.findEachWhile(Predicate)

findEach

<T> void findEach(Query<T> query,
                  int batch,
                  Consumer<List<T>> consumer,
                  Transaction t)

Execute findEach with batch consumer.

See Also:

Query.findEach(int, Consumer)

findEachWhile

<T> void findEachWhile(Query<T> query,
                       Predicate<T> consumer,
                       Transaction transaction)

Execute the query visiting the each bean one at a time.

Compared to findEach() this provides the ability to stop processing the query results early by returning false for the Predicate.

Unlike findList() this is suitable for processing a query that will return a very large resultSet. The reason is that not all the result beans need to be held in memory at the same time and instead processed one at a time.

Internally this query using a PersistenceContext scoped to each bean (and the beans associated object graph).

     DB.find(Order.class)
       .where().eq("status", Order.Status.NEW)
       .order().asc("id")
       .findEachWhile((Order order) -> {

         // do something with the order bean
         System.out.println(" -- processing order ... " + order);

         boolean carryOnProcessing = ...
         return carryOnProcessing;
       });

 

See Also:

Query.findEach(Consumer), Query.findEachWhile(Predicate)

findVersions

@Nonnull
<T> List<Version<T>> findVersions(Query<T> query,
                                  Transaction transaction)

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.

findList

@Nonnull
<T> List<T> findList(Query<T> query,
                     Transaction transaction)

Execute a query returning a list of beans.

Generally you are able to use Query.findList() rather than explicitly calling this method. You could use this method if you wish to explicitly control the transaction used for the query.

 List<Customer> customers = DB.find(Customer.class)
     .where().ilike("name", "rob%")
     .findList();

 

Type Parameters:

T - the type of entity bean to fetch.

Parameters:

query - the query to execute.

transaction - the transaction to use (can be null).

Returns:

the list of fetched beans.

See Also:

Query.findList()

findFutureCount

@Nonnull
<T> FutureRowCount<T> findFutureCount(Query<T> query,
                                      Transaction transaction)

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

Parameters:

query - the query to execute the row count on

transaction - the transaction (can be null).

Returns:

a Future object for the row count query

See Also:

Query.findFutureCount()

findFutureIds

@Nonnull
<T> FutureIds<T> findFutureIds(Query<T> query,
                               Transaction transaction)

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

Parameters:

query - the query to execute the fetch Id's on

transaction - the transaction (can be null).

Returns:

a Future object for the list of Id's

See Also:

Query.findFutureIds()

findFutureList

@Nonnull
<T> FutureList<T> findFutureList(Query<T> query,
                                 Transaction transaction)

Execute find list query in a background thread returning a FutureList object.

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

This query will execute in it's own PersistenceContext and using its own transaction. What that means is that it will not share any bean instances with other queries.

Parameters:

query - the query to execute in the background

transaction - the transaction (can be null).

Returns:

a Future object for the list result of the query

See Also:

Query.findFutureList()

findPagedList

@Nonnull
<T> PagedList<T> findPagedList(Query<T> query,
                               Transaction transaction)

Return a PagedList for this query using firstRow and maxRows.

The benefit of using this over findList() is that it provides functionality to get the total row count etc.

If maxRows is not set on the query prior to calling findPagedList() then a PersistenceException is thrown.

  PagedList<Order> pagedList = DB.find(Order.class)
       .setFirstRow(50)
       .setMaxRows(20)
       .findPagedList();

       // fetch the total row count in the background
       pagedList.loadRowCount();

       List<Order> orders = pagedList.getList();
       int totalRowCount = pagedList.getTotalRowCount();

 

Returns:

The PagedList

See Also:

Query.findPagedList()

findSet

@Nonnull
<T> Set<T> findSet(Query<T> query,
                   Transaction transaction)

Execute the query returning a set of entity beans.

Generally you are able to use Query.findSet() rather than explicitly calling this method. You could use this method if you wish to explicitly control the transaction used for the query.

 Set<Customer> customers = DB.find(Customer.class)
     .where().ilike("name", "rob%")
     .findSet();

 

Type Parameters:

T - the type of entity bean to fetch.

Parameters:

query - the query to execute

transaction - the transaction to use (can be null).

Returns:

the set of fetched beans.

See Also:

Query.findSet()

findMap

@Nonnull
<K,T> Map<K,T> findMap(Query<T> query,
                                   Transaction transaction)

Execute the query returning the entity beans in a Map.

Generally you are able to use Query.findMap() rather than explicitly calling this method. You could use this method if you wish to explicitly control the transaction used for the query.

Type Parameters:

T - the type of entity bean to fetch.

Parameters:

query - the query to execute.

transaction - the transaction to use (can be null).

Returns:

the map of fetched beans.

See Also:

Query.findMap()

findSingleAttributeList

@Nonnull
<A,T> List<A> findSingleAttributeList(Query<T> query,
                                            Transaction transaction)

Execute the query returning a list of values for a single property.

Example 1:

  List<String> names =
    DB.find(Customer.class)
      .select("name")
      .order().asc("name")
      .findSingleAttributeList();

 

Example 2:

  List<String> names =
    DB.find(Customer.class)
      .setDistinct(true)
      .select("name")
      .where().eq("status", Customer.Status.NEW)
      .order().asc("name")
      .setMaxRows(100)
      .findSingleAttributeList();

 

Returns:

the list of values for the selected property

See Also:

Query.findSingleAttributeList()

findOne

@Nullable
<T> T findOne(Query<T> query,
              Transaction transaction)

Execute the query returning at most one entity bean or null (if no matching bean is found).

This will throw a NonUniqueResultException if the query finds more than one result.

Generally you are able to use Query.findOne() rather than explicitly calling this method. You could use this method if you wish to explicitly control the transaction used for the query.

Type Parameters:

T - the type of entity bean to fetch.

Parameters:

query - the query to execute.

transaction - the transaction to use (can be null).

Returns:

the list of fetched beans.

Throws:

javax.persistence.NonUniqueResultException - if more than one result was found

See Also:

Query.findOne()

findOneOrEmpty

@Nonnull
<T> Optional<T> findOneOrEmpty(Query<T> query,
                               Transaction transaction)

Similar to findOne() but returns an Optional (rather than nullable).

delete

<T> int delete(Query<T> query,
               Transaction transaction)

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.

Type Parameters:

T - the type of entity bean to fetch.

Parameters:

query - the query used for the delete

transaction - the transaction to use (can be null)

Returns:

the number of beans/rows that were deleted

update

<T> int update(Query<T> query,
               Transaction transaction)

Execute the update query returning the number of rows updated.

The update query must be created using Database.update(Class).

Type Parameters:

T - the type of entity bean

Parameters:

query - the update query to execute

transaction - the optional transaction to use for the update (can be null)

Returns:

The number of rows updated

findList

@Nonnull
List<SqlRow> findList(SqlQuery query,
                      Transaction transaction)

Execute the sql query returning a list of MapBean.

Generally you are able to use SqlQuery.findList() rather than explicitly calling this method. You could use this method if you wish to explicitly control the transaction used for the query.

Parameters:

query - the query to execute.

transaction - the transaction to use (can be null).

Returns:

the list of fetched MapBean.

See Also:

SqlQuery.findList()

findEach

void findEach(SqlQuery query,
              Consumer<SqlRow> consumer,
              Transaction transaction)

Execute the SqlQuery iterating a row at a time.

This streaming type query is useful for large query execution as only 1 row needs to be held in memory.

findEachWhile

void findEachWhile(SqlQuery query,
                   Predicate<SqlRow> consumer,
                   Transaction transaction)

Execute the SqlQuery iterating a row at a time with the ability to stop consuming part way through.

Returning false after processing a row stops the iteration through the query results.

This streaming type query is useful for large query execution as only 1 row needs to be held in memory.

findOne

@Nullable
SqlRow findOne(SqlQuery query,
               Transaction transaction)

Execute the sql query returning a single MapBean or null.

This will throw a PersistenceException if the query found more than one result.

Generally you are able to use SqlQuery.findOne() rather than explicitly calling this method. You could use this method if you wish to explicitly control the transaction used for the query.

Parameters:

query - the query to execute.

transaction - the transaction to use (can be null).

Returns:

the fetched MapBean or null if none was found.

See Also:

SqlQuery.findOne()