001package com.avaje.ebean;
002
003import java.io.Serializable;
004import java.util.List;
005import java.util.Map;
006import java.util.Set;
007
008/**
009 * Query object for performing native SQL queries that return SqlRow's.
010 * <p>
011 * Firstly note that you can use your own sql queries with <em>entity beans</em>
012 * by using the SqlSelect annotation. This should be your first approach when
013 * wanting to use your own SQL queries.
014 * </p>
015 * <p>
016 * If ORM Mapping is too tight and constraining for your problem then SqlQuery
017 * could be a good approach.
018 * </p>
019 * <p>
020 * The returned SqlRow objects are similar to a LinkedHashMap with some type
021 * conversion support added.
022 * </p>
023 * 
024 * <pre class="code">
025 * // its typically a good idea to use a named query
026 * // and put the sql in the orm.xml instead of in your code
027 * 
028 * String sql = &quot;select id, name from customer where name like :name and status_code = :status&quot;;
029 * 
030 * SqlQuery sqlQuery = Ebean.createSqlQuery(sql);
031 * sqlQuery.setParameter(&quot;name&quot;, &quot;Acme%&quot;);
032 * sqlQuery.setParameter(&quot;status&quot;, &quot;ACTIVE&quot;);
033 * 
034 * // execute the query returning a List of MapBean objects
035 * List&lt;SqlRow&gt; list = sqlQuery.findList();
036 * </pre>
037 * 
038 */
039public interface SqlQuery extends Serializable {
040
041  /**
042   * Cancel the query if support by the underlying database and driver.
043   * <p>
044   * This must be called from a different thread to the one executing the query.
045   * </p>
046   */
047  void cancel();
048
049  /**
050   * Execute the query returning a list.
051   */
052  List<SqlRow> findList();
053
054  /**
055   * Execute the query returning a set.
056   */
057  Set<SqlRow> findSet();
058
059  /**
060   * Execute the query returning a map.
061   */
062  Map<?, SqlRow> findMap();
063
064  /**
065   * Execute the query returning a single row or null.
066   * <p>
067   * If this query finds 2 or more rows then it will throw a
068   * PersistenceException.
069   * </p>
070   */
071  SqlRow findUnique();
072
073  /**
074   * Execute find list SQL query in a background thread.
075   * <p>
076   * This returns a Future object which can be used to cancel, check the
077   * execution status (isDone etc) and get the value (with or without a
078   * timeout).
079   * </p>
080   * 
081   * @return a Future object for the list result of the query
082   * @deprecated
083   */
084  SqlFutureList findFutureList();
085
086  /**
087   * The same as bind for named parameters.
088   */
089  SqlQuery setParameter(String name, Object value);
090
091  /**
092   * The same as bind for positioned parameters.
093   */
094  SqlQuery setParameter(int position, Object value);
095
096  /**
097   * Set a listener to process the query on a row by row basis.
098   * <p>
099   * It this case the rows are not loaded into the persistence context and
100   * instead can be processed by the query listener.
101   * </p>
102   * <p>
103   * Use this when you want to process a large query and do not want to hold the
104   * entire query result in memory.
105   * </p>
106   */
107  SqlQuery setListener(SqlQueryListener queryListener);
108
109  /**
110   * Set the index of the first row of the results to return.
111   */
112  SqlQuery setFirstRow(int firstRow);
113
114  /**
115   * Set the maximum number of query results to return.
116   */
117  SqlQuery setMaxRows(int maxRows);
118
119  /**
120   * Set the index after which fetching continues in a background thread.
121   */
122  SqlQuery setBackgroundFetchAfter(int backgroundFetchAfter);
123
124  /**
125   * Set the column to use to determine the keys for a Map.
126   */
127  SqlQuery setMapKey(String mapKey);
128
129  /**
130   * Set a timeout on this query.
131   * <p>
132   * This will typically result in a call to setQueryTimeout() on a
133   * preparedStatement. If the timeout occurs an exception will be thrown - this
134   * will be a SQLException wrapped up in a PersistenceException.
135   * </p>
136   * 
137   * @param secs
138   *          the query timeout limit in seconds. Zero means there is no limit.
139   */
140  SqlQuery setTimeout(int secs);
141
142  /**
143   * A hint which for JDBC translates to the Statement.fetchSize().
144   * <p>
145   * Gives the JDBC driver a hint as to the number of rows that should be
146   * fetched from the database when more rows are needed for ResultSet.
147   * </p>
148   */
149  SqlQuery setBufferFetchSizeHint(int bufferFetchSizeHint);
150
151}