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}