001package com.avaje.ebean;
002
003import java.io.Serializable;
004import java.util.List;
005
006/**
007 * Query object for performing native SQL queries that return SqlRow's.
008 * <p>
009 * Firstly note that you can use your own sql queries with <em>entity beans</em>
010 * by using the SqlSelect annotation. This should be your first approach when
011 * wanting to use your own SQL queries.
012 * </p>
013 * <p>
014 * If ORM Mapping is too tight and constraining for your problem then SqlQuery
015 * could be a good approach.
016 * </p>
017 * <p>
018 * The returned SqlRow objects are similar to a LinkedHashMap with some type
019 * conversion support added.
020 * </p>
021 * 
022 * <pre>{@code
023 *
024 *   // its typically a good idea to use a named query
025 *   // and put the sql in the orm.xml instead of in your code
026 * 
027 *   String sql = "select id, name from customer where name like :name and status_code = :status";
028 * 
029 *   SqlQuery sqlQuery = Ebean.createSqlQuery(sql);
030 *   sqlQuery.setParameter("name", "Acme%");
031 *   sqlQuery.setParameter("status", "ACTIVE");
032 * 
033 *   // execute the query returning a List of MapBean objects
034 *   List<SqlRow> list = sqlQuery.findList();
035 *
036 * }</pre>
037 * 
038 */
039public interface SqlQuery extends Serializable {
040
041  /**
042   * Execute the query returning a list.
043   */
044  List<SqlRow> findList();
045
046  /**
047   * Execute the SqlQuery iterating a row at a time.
048   * <p>
049   * This streaming type query is useful for large query execution as only 1 row needs to be held in memory.
050   * </p>
051   */
052  void findEach(QueryEachConsumer<SqlRow> consumer);
053
054  /**
055   * Execute the SqlQuery iterating a row at a time with the ability to stop consuming part way through.
056   * <p>
057   * Returning false after processing a row stops the iteration through the query results.
058   * </p>
059   * <p>
060   * This streaming type query is useful for large query execution as only 1 row needs to be held in memory.
061   * </p>
062   */
063  void findEachWhile(QueryEachWhileConsumer<SqlRow> consumer);
064
065  /**
066   * Execute the query returning a single row or null.
067   * <p>
068   * If this query finds 2 or more rows then it will throw a
069   * PersistenceException.
070   * </p>
071   */
072  SqlRow findUnique();
073
074  /**
075   * The same as bind for named parameters.
076   */
077  SqlQuery setParameter(String name, Object value);
078
079  /**
080   * The same as bind for positioned parameters.
081   */
082  SqlQuery setParameter(int position, Object value);
083
084  /**
085   * Set the index of the first row of the results to return.
086   */
087  SqlQuery setFirstRow(int firstRow);
088
089  /**
090   * Set the maximum number of query results to return.
091   */
092  SqlQuery setMaxRows(int maxRows);
093
094  /**
095   * Set a timeout on this query.
096   * <p>
097   * This will typically result in a call to setQueryTimeout() on a
098   * preparedStatement. If the timeout occurs an exception will be thrown - this
099   * will be a SQLException wrapped up in a PersistenceException.
100   * </p>
101   * 
102   * @param secs
103   *          the query timeout limit in seconds. Zero means there is no limit.
104   */
105  SqlQuery setTimeout(int secs);
106
107  /**
108   * A hint which for JDBC translates to the Statement.fetchSize().
109   * <p>
110   * Gives the JDBC driver a hint as to the number of rows that should be
111   * fetched from the database when more rows are needed for ResultSet.
112   * </p>
113   */
114  SqlQuery setBufferFetchSizeHint(int bufferFetchSizeHint);
115
116}