Module io.ebean.api
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 Details

    • 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<T> 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:

    • findIds

      <A, T> List<A> findIds(Query<T> query, Transaction transaction)
      Return the Id values of the query as a List.
      See Also:

    • findIterate

      <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:

    • findStream

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

    • 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:

    • findEach

      <T> void findEach(Query<T> query, int batch, Consumer<List<T>> consumer, Transaction t)
      Execute findEach with batch consumer.
      See Also:

    • 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:

    • findVersions

      <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

      <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:

    • findFutureCount

      <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:

    • findFutureIds

      <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:

    • findFutureList

      <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:

    • findPagedList

      <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:

    • findSet

      <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:

    • findMap

      <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:

    • findSingleAttributeList

      <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:

    • 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:

    • findOneOrEmpty

      <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

      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:

    • 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: