001: /*-------------------------------------------------------------------------
002: *
003: * Copyright (c) 2003-2005, PostgreSQL Global Development Group
004: * Copyright (c) 2004, Open Cloud Limited.
005: *
006: * IDENTIFICATION
007: * $PostgreSQL: pgjdbc/org/postgresql/core/QueryExecutor.java,v 1.40 2005/02/01 07:27:53 jurka Exp $
008: *
009: *-------------------------------------------------------------------------
010: */
011: package org.postgresql.core;
012:
013: import java.sql.SQLException;
014:
015: /**
016: * Abstracts the protocol-specific details of executing a query.
017: *<p>
018: * Every connection has a single QueryExecutor implementation associated with it.
019: * This object provides:
020: *
021: * <ul>
022: * <li> factory methods for Query objects ({@link #createSimpleQuery}
023: * and {@link #createParameterizedQuery})
024: * <li> execution methods for created Query objects ({@link #execute(Query,ParameterList,ResultHandler,int,int,int)}
025: * for single queries and {@link #execute(Query[],ParameterList[],ResultHandler,int,int,int)} for batches of
026: * queries)
027: * <li> a fastpath call interface ({@link #createFastpathParameters}
028: * and {@link #fastpathCall}).
029: * </ul>
030: *
031: *<p>
032: * Query objects may represent a query that has parameter placeholders. To provide
033: * actual values for these parameters, a {@link ParameterList} object is created
034: * via a factory method ({@link Query#createParameterList}). The parameters are filled
035: * in by the caller and passed along with the query to the query execution methods.
036: * Several ParameterLists for a given query might exist at one time (or over time);
037: * this allows the underlying Query to be reused for several executions, or for
038: * batch execution of the same Query.
039: *
040: *<p>
041: * In general, a Query created by a particular QueryExecutor may only be
042: * executed by that QueryExecutor, and a ParameterList created by a particular
043: * Query may only be used as parameters to that Query. Unpredictable things will
044: * happen if this isn't done.
045: *
046: * @author Oliver Jowett (oliver@opencloud.com)
047: */
048: public interface QueryExecutor {
049: /**
050: * Flag for query execution that indicates the given Query object is unlikely
051: * to be reused.
052: */
053: static int QUERY_ONESHOT = 1;
054:
055: /**
056: * Flag for query execution that indicates that resultset metadata isn't needed
057: * and can be safely omitted.
058: */
059: static int QUERY_NO_METADATA = 2;
060:
061: /**
062: * Flag for query execution that indicates that a resultset isn't expected and
063: * the query executor can safely discard any rows (although the resultset should
064: * still appear to be from a resultset-returning query).
065: */
066: static int QUERY_NO_RESULTS = 4;
067:
068: /**
069: * Flag for query execution that indicates a forward-fetch-capable cursor should
070: * be used if possible.
071: */
072: static int QUERY_FORWARD_CURSOR = 8;
073:
074: /**
075: * Flag for query execution that indicates the automatic BEGIN on the first statement
076: * when outside a transaction should not be done.
077: */
078: static int QUERY_SUPPRESS_BEGIN = 16;
079:
080: /**
081: * Flag for query execution when we don't really want to execute, we just
082: * want to get the parameter metadata for the statement.
083: */
084: static int QUERY_DESCRIBE_ONLY = 32;
085:
086: /**
087: * Execute a Query, passing results to a provided ResultHandler.
088: *
089: * @param query the query to execute; must be a query returned from
090: * calling {@link #createSimpleQuery(String)} or {@link #createParameterizedQuery(String)}
091: * on this QueryExecutor object.
092: * @param parameters the parameters for the query. Must be non-<code>null</code>
093: * if the query takes parameters. Must be a parameter object returned by
094: * {@link org.postgresql.core.Query#createParameterList()}.
095: * @param handler a ResultHandler responsible for handling results generated
096: * by this query
097: * @param maxRows the maximum number of rows to retrieve
098: * @param fetchSize if QUERY_FORWARD_CURSOR is set, the preferred number of rows to retrieve before suspending
099: * @param flags a combination of QUERY_* flags indicating how to handle the query.
100: *
101: * @throws SQLException if query execution fails
102: */
103: void execute(Query query, ParameterList parameters,
104: ResultHandler handler, int maxRows, int fetchSize, int flags)
105: throws SQLException;
106:
107: /**
108: * Execute several Query, passing results to a provided ResultHandler.
109: *
110: * @param queries the queries to execute; each must be a query returned from
111: * calling {@link #createSimpleQuery(String)} or {@link #createParameterizedQuery(String)}
112: * on this QueryExecutor object.
113: * @param parameterLists the parameter lists for the queries. The parameter lists
114: * correspond 1:1 to the queries passed in the <code>queries</code> array. Each must be
115: * non-<code>null</code> if the corresponding query takes parameters, and must
116: * be a parameter object returned by {@link org.postgresql.core.Query#createParameterList()}
117: * created by the corresponding query.
118: * @param handler a ResultHandler responsible for handling results generated
119: * by this query
120: * @param maxRows the maximum number of rows to retrieve
121: * @param fetchSize if QUERY_FORWARD_CURSOR is set, the preferred number of rows to retrieve before suspending
122: * @param flags a combination of QUERY_* flags indicating how to handle the query.
123: *
124: * @throws SQLException if query execution fails
125: */
126: void execute(Query[] queries, ParameterList[] parameterLists,
127: ResultHandler handler, int maxRows, int fetchSize, int flags)
128: throws SQLException;
129:
130: /**
131: * Fetch additional rows from a cursor.
132: *
133: * @param cursor the cursor to fetch from
134: * @param handler the handler to feed results to
135: * @param fetchSize the preferred number of rows to retrieve before suspending
136: * @throws SQLException if query execution fails
137: */
138: void fetch(ResultCursor cursor, ResultHandler handler, int fetchSize)
139: throws SQLException;
140:
141: /**
142: * Create an unparameterized Query object suitable for execution by
143: * this QueryExecutor. The provided query string is not parsed for
144: * parameter placeholders ('?' characters), and the
145: * {@link Query#createParameterList} of the returned object will
146: * always return an empty ParameterList.
147: *
148: * @param sql the SQL for the query to create
149: * @return a new Query object
150: */
151: Query createSimpleQuery(String sql);
152:
153: /**
154: * Create a parameterized Query object suitable for execution by
155: * this QueryExecutor. The provided query string is parsed for
156: * parameter placeholders ('?' characters), and the
157: * {@link Query#createParameterList} of the returned object will
158: * create an appropriately-sized ParameterList.
159: *
160: * @param sql the SQL for the query to create, with '?' placeholders for
161: * parameters.
162: * @return a new Query object
163: */
164: Query createParameterizedQuery(String sql); // Parsed for parameter placeholders ('?')
165:
166: //
167: // Fastpath interface.
168: //
169:
170: /**
171: * Create a new ParameterList implementation suitable for invoking a
172: * fastpath function via {@link #fastpathCall}.
173: *
174: * @param count the number of parameters the fastpath call will take
175: * @return a ParameterList suitable for passing to {@link #fastpathCall}.
176: */
177: ParameterList createFastpathParameters(int count);
178:
179: /**
180: * Invoke a backend function via the fastpath interface.
181: *
182: * @param fnid the OID of the backend function to invoke
183: * @param params a ParameterList returned from {@link #createFastpathParameters}
184: * containing the parameters to pass to the backend function
185: *
186: * @return the binary-format result of the fastpath call, or <code>null</code>
187: * if a void result was returned
188: * @throws SQLException if an error occurs while executing the fastpath call
189: */
190: byte[] fastpathCall(int fnid, ParameterList params,
191: boolean suppressBegin) throws SQLException;
192: }
|