1
/*****************************************************************************
2
* Copyright (C) 2008 EnterpriseDB Corporation.
3
* Copyright (C) 2011 Stado Global Development Group.
5
* This file is part of Stado.
7
* Stado is free software: you can redistribute it and/or modify
8
* it under the terms of the GNU General Public License as published by
9
* the Free Software Foundation, either version 3 of the License, or
10
* (at your option) any later version.
12
* Stado is distributed in the hope that it will be useful,
13
* but WITHOUT ANY WARRANTY; without even the implied warranty of
14
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15
* GNU General Public License for more details.
17
* You should have received a copy of the GNU General Public License
18
* along with Stado. If not, see <http://www.gnu.org/licenses/>.
20
* You can find Stado at http://www.stado.us
22
****************************************************************************/
23
package org.postgresql.driver.core;
25
import java.sql.SQLException;
27
import org.postgresql.driver.copy.CopyOperation;
30
* Abstracts the protocol-specific details of executing a query.
32
* Every connection has a single QueryExecutor implementation associated with it.
33
* This object provides:
36
* <li> factory methods for Query objects ({@link #createSimpleQuery}
37
* and {@link #createParameterizedQuery})
38
* <li> execution methods for created Query objects ({@link #execute(Query,ParameterList,ResultHandler,int,int,int)}
39
* for single queries and {@link #execute(Query[],ParameterList[],ResultHandler,int,int,int)} for batches of
41
* <li> a fastpath call interface ({@link #createFastpathParameters}
42
* and {@link #fastpathCall}).
46
* Query objects may represent a query that has parameter placeholders. To provide
47
* actual values for these parameters, a {@link ParameterList} object is created
48
* via a factory method ({@link Query#createParameterList}). The parameters are filled
49
* in by the caller and passed along with the query to the query execution methods.
50
* Several ParameterLists for a given query might exist at one time (or over time);
51
* this allows the underlying Query to be reused for several executions, or for
52
* batch execution of the same Query.
55
* In general, a Query created by a particular QueryExecutor may only be
56
* executed by that QueryExecutor, and a ParameterList created by a particular
57
* Query may only be used as parameters to that Query. Unpredictable things will
58
* happen if this isn't done.
60
* @author Oliver Jowett (oliver@opencloud.com)
62
public interface QueryExecutor {
64
* Flag for query execution that indicates the given Query object is unlikely
67
static int QUERY_ONESHOT = 1;
70
* Flag for query execution that indicates that resultset metadata isn't needed
71
* and can be safely omitted.
73
static int QUERY_NO_METADATA = 2;
76
* Flag for query execution that indicates that a resultset isn't expected and
77
* the query executor can safely discard any rows (although the resultset should
78
* still appear to be from a resultset-returning query).
80
static int QUERY_NO_RESULTS = 4;
83
* Flag for query execution that indicates a forward-fetch-capable cursor should
84
* be used if possible.
86
static int QUERY_FORWARD_CURSOR = 8;
89
* Flag for query execution that indicates the automatic BEGIN on the first statement
90
* when outside a transaction should not be done.
92
static int QUERY_SUPPRESS_BEGIN = 16;
95
* Flag for query execution when we don't really want to execute, we just
96
* want to get the parameter metadata for the statement.
98
static int QUERY_DESCRIBE_ONLY = 32;
101
* Flag for query execution used by generated keys where we want to receive
102
* both the ResultSet and associated update count from the command status.
104
static int QUERY_BOTH_ROWS_AND_STATUS = 64;
107
* Execute a Query, passing results to a provided ResultHandler.
109
* @param query the query to execute; must be a query returned from
110
* calling {@link #createSimpleQuery(String)} or {@link #createParameterizedQuery(String)}
111
* on this QueryExecutor object.
112
* @param parameters the parameters for the query. Must be non-<code>null</code>
113
* if the query takes parameters. Must be a parameter object returned by
114
* {@link org.postgresql.driver.core.Query#createParameterList()}.
115
* @param handler a ResultHandler responsible for handling results generated
117
* @param maxRows the maximum number of rows to retrieve
118
* @param fetchSize if QUERY_FORWARD_CURSOR is set, the preferred number of rows to retrieve before suspending
119
* @param flags a combination of QUERY_* flags indicating how to handle the query.
121
* @throws SQLException if query execution fails
123
void execute(Query query,
124
ParameterList parameters,
125
ResultHandler handler,
132
* Execute several Query, passing results to a provided ResultHandler.
134
* @param queries the queries to execute; each must be a query returned from
135
* calling {@link #createSimpleQuery(String)} or {@link #createParameterizedQuery(String)}
136
* on this QueryExecutor object.
137
* @param parameterLists the parameter lists for the queries. The parameter lists
138
* correspond 1:1 to the queries passed in the <code>queries</code> array. Each must be
139
* non-<code>null</code> if the corresponding query takes parameters, and must
140
* be a parameter object returned by {@link org.postgresql.driver.core.Query#createParameterList()}
141
* created by the corresponding query.
142
* @param handler a ResultHandler responsible for handling results generated
144
* @param maxRows the maximum number of rows to retrieve
145
* @param fetchSize if QUERY_FORWARD_CURSOR is set, the preferred number of rows to retrieve before suspending
146
* @param flags a combination of QUERY_* flags indicating how to handle the query.
148
* @throws SQLException if query execution fails
150
void execute(Query[] queries,
151
ParameterList[] parameterLists,
152
ResultHandler handler,
159
* Fetch additional rows from a cursor.
161
* @param cursor the cursor to fetch from
162
* @param handler the handler to feed results to
163
* @param fetchSize the preferred number of rows to retrieve before suspending
164
* @throws SQLException if query execution fails
166
void fetch(ResultCursor cursor, ResultHandler handler, int fetchSize) throws SQLException;
169
* Create an unparameterized Query object suitable for execution by
170
* this QueryExecutor. The provided query string is not parsed for
171
* parameter placeholders ('?' characters), and the
172
* {@link Query#createParameterList} of the returned object will
173
* always return an empty ParameterList.
175
* @param sql the SQL for the query to create
176
* @return a new Query object
178
Query createSimpleQuery(String sql);
181
* Create a parameterized Query object suitable for execution by
182
* this QueryExecutor. The provided query string is parsed for
183
* parameter placeholders ('?' characters), and the
184
* {@link Query#createParameterList} of the returned object will
185
* create an appropriately-sized ParameterList.
187
* @param sql the SQL for the query to create, with '?' placeholders for
189
* @return a new Query object
191
Query createParameterizedQuery(String sql); // Parsed for parameter placeholders ('?')
194
* Prior to attempting to retrieve notifications, we need to pull
195
* any recently received notifications off of the network buffers.
196
* The notification retrieval in ProtocolConnection cannot do this
197
* as it is prone to deadlock, so the higher level caller must be
198
* responsible which requires exposing this method.
200
void processNotifies() throws SQLException;
203
// Fastpath interface.
207
* Create a new ParameterList implementation suitable for invoking a
208
* fastpath function via {@link #fastpathCall}.
210
* @param count the number of parameters the fastpath call will take
211
* @return a ParameterList suitable for passing to {@link #fastpathCall}.
213
ParameterList createFastpathParameters(int count);
216
* Invoke a backend function via the fastpath interface.
218
* @param fnid the OID of the backend function to invoke
219
* @param params a ParameterList returned from {@link #createFastpathParameters}
220
* containing the parameters to pass to the backend function
222
* @return the binary-format result of the fastpath call, or <code>null</code>
223
* if a void result was returned
224
* @throws SQLException if an error occurs while executing the fastpath call
226
byte[] fastpathCall(int fnid, ParameterList params, boolean suppressBegin) throws SQLException;
229
* Issues a COPY FROM STDIN / COPY TO STDOUT statement and returns
230
* handler for associated operation. Until the copy operation completes,
231
* no other database operation may be performed.
232
* Implemented for protocol version 3 only.
233
* @throws SQLException when initializing the given query fails
235
CopyOperation startCopy(String sql, boolean suppressBegin) throws SQLException;
added
removed
src/org/postgresql/driver/core/QueryExecutor.java
