001package io.ebean;
002
003import javax.annotation.Nonnull;
004import javax.annotation.Nullable;
005import java.util.List;
006import java.util.Optional;
007import java.util.function.Consumer;
008import java.util.function.Predicate;
009
010/**
011 * Query for performing native SQL queries that return DTO Bean's.
012 * <p>
013 * These beans are just normal classes. They must have public constructors
014 * and setters.
015 * <p>
016 * Constructors with arguments are used if the number of constructor arguments
017 * matches the number of columns in the resultSet.
018 * </p>
019 * <p>
020 * If the number of columns in the resultSet is greater than the largest constructor
021 * then the largest constructor is used for the first columns and remaining columns
022 * are mapped by setter methods.
023 * </p>
024 *
025 * <pre>{@code
026 *
027 *   // CustomerDto is just a 'bean like' class
028 *   // with public constructor(s) and public setter methods
029 *
030 *   String sql = "select id, name from customer where name like :name and status_code = :status";
031 *
032 *   List<CustomerDto> beans =
033 *     DB.findDto(CustomerDto.class, sql)
034 *     .setParameter("name", "Acme%")
035 *     .setParameter("status", "ACTIVE")
036 *     .findList();
037 *
038 * }</pre>
039 */
040public interface DtoQuery<T> {
041
042  /**
043   * Execute the query returning a list.
044   */
045  @Nonnull
046  List<T> findList();
047
048  /**
049   * Execute the query iterating a row at a time.
050   * <p>
051   * This streaming type query is useful for large query execution as only 1 row needs to be held in memory.
052   * </p>
053   */
054  void findEach(Consumer<T> consumer);
055
056  /**
057   * Execute the query iterating a row at a time with the ability to stop consuming part way through.
058   * <p>
059   * Returning false after processing a row stops the iteration through the query results.
060   * </p>
061   * <p>
062   * This streaming type query is useful for large query execution as only 1 row needs to be held in memory.
063   * </p>
064   */
065  void findEachWhile(Predicate<T> consumer);
066
067  /**
068   * Execute the query returning a single bean.
069   */
070  @Nullable
071  T findOne();
072
073  /**
074   * Execute the query returning an optional bean.
075   */
076  @Nonnull
077  Optional<T> findOneOrEmpty();
078
079  /**
080   * The same as bind for named parameters.
081   */
082  DtoQuery<T> setParameter(String name, Object value);
083
084  /**
085   * The same as bind for positioned parameters.
086   */
087  DtoQuery<T> setParameter(int position, Object value);
088
089  /**
090   * Set the index of the first row of the results to return.
091   */
092  DtoQuery<T> setFirstRow(int firstRow);
093
094  /**
095   * Set the maximum number of query results to return.
096   */
097  DtoQuery<T> setMaxRows(int maxRows);
098
099  /**
100   * When resultSet columns are not able to be mapped to a bean property then instead of
101   * throwing effectively skip reading that column.
102   */
103  DtoQuery<T> setRelaxedMode();
104
105  /**
106   * Set a label on the query to make it easier to identify queries related to query execution statistics.
107   *
108   * @param label A label that is unique to the DTO bean type.
109   */
110  DtoQuery<T> setLabel(String label);
111
112  /**
113   * Set a timeout on this query.
114   * <p>
115   * This will typically result in a call to setQueryTimeout() on a
116   * preparedStatement. If the timeout occurs an exception will be thrown - this
117   * will be a SQLException wrapped up in a PersistenceException.
118   * </p>
119   *
120   * @param secs the query timeout limit in seconds. Zero means there is no limit.
121   */
122  DtoQuery<T> setTimeout(int secs);
123
124  /**
125   * A hint which for JDBC translates to the Statement.fetchSize().
126   * <p>
127   * Gives the JDBC driver a hint as to the number of rows that should be
128   * fetched from the database when more rows are needed for ResultSet.
129   * </p>
130   */
131  DtoQuery<T> setBufferFetchSizeHint(int bufferFetchSizeHint);
132
133}