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   * Bind all the parameters using index positions.
081   * <p>
082   * Binds each parameter moving the index position each time.
083   * <p>
084   * A convenience for multiple calls to {@link #setParameter(Object)}
085   */
086  DtoQuery<T> setParameters(Object... value);
087
088  /**
089   * Bind the next parameter using index position.
090   * <p>
091   * Bind the parameter using index position starting at 1 and incrementing.
092   * <p>
093   */
094  DtoQuery<T> setParameter(Object value);
095
096  /**
097   * Bind the named parameter.
098   */
099  DtoQuery<T> setParameter(String name, Object value);
100
101  /**
102   * Bind the parameter by its index position (1 based like JDBC).
103   */
104  DtoQuery<T> setParameter(int position, Object value);
105
106  /**
107   * Set the index of the first row of the results to return.
108   */
109  DtoQuery<T> setFirstRow(int firstRow);
110
111  /**
112   * Set the maximum number of query results to return.
113   */
114  DtoQuery<T> setMaxRows(int maxRows);
115
116  /**
117   * When resultSet columns are not able to be mapped to a bean property then instead of
118   * throwing effectively skip reading that column.
119   */
120  DtoQuery<T> setRelaxedMode();
121
122  /**
123   * Set a label on the query to make it easier to identify queries related to query execution statistics.
124   *
125   * @param label A label that is unique to the DTO bean type.
126   */
127  DtoQuery<T> setLabel(String label);
128
129  /**
130   * Set the profile location of this query. This is used to relate query execution metrics
131   * back to a location like a specific line of code.
132   */
133  DtoQuery<T> setProfileLocation(ProfileLocation profileLocation);
134
135  /**
136   * Set a timeout on this query.
137   * <p>
138   * This will typically result in a call to setQueryTimeout() on a
139   * preparedStatement. If the timeout occurs an exception will be thrown - this
140   * will be a SQLException wrapped up in a PersistenceException.
141   * </p>
142   *
143   * @param secs the query timeout limit in seconds. Zero means there is no limit.
144   */
145  DtoQuery<T> setTimeout(int secs);
146
147  /**
148   * A hint which for JDBC translates to the Statement.fetchSize().
149   * <p>
150   * Gives the JDBC driver a hint as to the number of rows that should be
151   * fetched from the database when more rows are needed for ResultSet.
152   * </p>
153   */
154  DtoQuery<T> setBufferFetchSizeHint(int bufferFetchSizeHint);
155
156  /**
157   * Use the explicit transaction to execute the query.
158   */
159  DtoQuery<T> usingTransaction(Transaction transaction);
160}