public interface QueryExecutor
Every connection has a single QueryExecutor implementation associated with it. This object provides:
createSimpleQuery(java.lang.String)
and createParameterizedQuery(java.lang.String)
)
execute(Query,ParameterList,ResultHandler,int,int,int)
for single queries and execute(Query[],ParameterList[],ResultHandler,int,int,int)
for batches of
queries)
createFastpathParameters(int)
and fastpathCall(int, org.postgresql.core.ParameterList, boolean)
).
Query objects may represent a query that has parameter placeholders. To provide
actual values for these parameters, a ParameterList
object is created
via a factory method (Query.createParameterList()
). The parameters are filled
in by the caller and passed along with the query to the query execution methods.
Several ParameterLists for a given query might exist at one time (or over time);
this allows the underlying Query to be reused for several executions, or for
batch execution of the same Query.
In general, a Query created by a particular QueryExecutor may only be executed by that QueryExecutor, and a ParameterList created by a particular Query may only be used as parameters to that Query. Unpredictable things will happen if this isn't done.
Modifier and Type | Field and Description |
---|---|
static int |
QUERY_BOTH_ROWS_AND_STATUS
Flag for query execution used by generated keys where we want to receive
both the ResultSet and associated update count from the command status.
|
static int |
QUERY_DESCRIBE_ONLY
Flag for query execution when we don't really want to execute, we just
want to get the parameter metadata for the statement.
|
static int |
QUERY_DISALLOW_BATCHING
Deprecated.
in PgJDBC 9.4 as we now auto-size batches.
|
static int |
QUERY_FORCE_DESCRIBE_PORTAL
Force this query to be described at each execution.
|
static int |
QUERY_FORWARD_CURSOR
Flag for query execution that indicates a forward-fetch-capable cursor should
be used if possible.
|
static int |
QUERY_NO_BINARY_TRANSFER
Flag for query execution to avoid using binary transfer.
|
static int |
QUERY_NO_METADATA
Flag for query execution that indicates that resultset metadata isn't needed
and can be safely omitted.
|
static int |
QUERY_NO_RESULTS
Flag for query execution that indicates that a resultset isn't expected and
the query executor can safely discard any rows (although the resultset should
still appear to be from a resultset-returning query).
|
static int |
QUERY_ONESHOT
Flag for query execution that indicates the given Query object is unlikely
to be reused.
|
static int |
QUERY_SUPPRESS_BEGIN
Flag for query execution that indicates the automatic BEGIN on the first statement
when outside a transaction should not be done.
|
Modifier and Type | Method and Description |
---|---|
ParameterList |
createFastpathParameters(int count)
Create a new ParameterList implementation suitable for invoking a
fastpath function via
fastpathCall(int, org.postgresql.core.ParameterList, boolean) . |
Query |
createParameterizedQuery(String sql)
Create a parameterized Query object suitable for execution by
this QueryExecutor.
|
Query |
createSimpleQuery(String sql)
Create an unparameterized Query object suitable for execution by
this QueryExecutor.
|
void |
execute(Query[] queries,
ParameterList[] parameterLists,
ResultHandler handler,
int maxRows,
int fetchSize,
int flags)
Execute several Query, passing results to a provided ResultHandler.
|
void |
execute(Query query,
ParameterList parameters,
ResultHandler handler,
int maxRows,
int fetchSize,
int flags)
Execute a Query, passing results to a provided ResultHandler.
|
byte[] |
fastpathCall(int fnid,
ParameterList params,
boolean suppressBegin)
Invoke a backend function via the fastpath interface.
|
void |
fetch(ResultCursor cursor,
ResultHandler handler,
int fetchSize)
Fetch additional rows from a cursor.
|
void |
processNotifies()
Prior to attempting to retrieve notifications, we need to pull
any recently received notifications off of the network buffers.
|
CopyOperation |
startCopy(String sql,
boolean suppressBegin)
Issues a COPY FROM STDIN / COPY TO STDOUT statement and returns
handler for associated operation.
|
static final int QUERY_ONESHOT
static final int QUERY_NO_METADATA
static final int QUERY_NO_RESULTS
static final int QUERY_FORWARD_CURSOR
static final int QUERY_SUPPRESS_BEGIN
static final int QUERY_DESCRIBE_ONLY
static final int QUERY_BOTH_ROWS_AND_STATUS
static final int QUERY_FORCE_DESCRIBE_PORTAL
@Deprecated static final int QUERY_DISALLOW_BATCHING
static final int QUERY_NO_BINARY_TRANSFER
void execute(Query query, ParameterList parameters, ResultHandler handler, int maxRows, int fetchSize, int flags) throws SQLException
query
- the query to execute; must be a query returned from
calling createSimpleQuery(String)
or createParameterizedQuery(String)
on this QueryExecutor object.parameters
- the parameters for the query. Must be non-null
if the query takes parameters. Must be a parameter object returned by
Query.createParameterList()
.handler
- a ResultHandler responsible for handling results generated
by this querymaxRows
- the maximum number of rows to retrievefetchSize
- if QUERY_FORWARD_CURSOR is set, the preferred number of rows to retrieve before suspendingflags
- a combination of QUERY_* flags indicating how to handle the query.SQLException
- if query execution failsvoid execute(Query[] queries, ParameterList[] parameterLists, ResultHandler handler, int maxRows, int fetchSize, int flags) throws SQLException
queries
- the queries to execute; each must be a query returned from
calling createSimpleQuery(String)
or createParameterizedQuery(String)
on this QueryExecutor object.parameterLists
- the parameter lists for the queries. The parameter lists
correspond 1:1 to the queries passed in the queries
array. Each must be
non-null
if the corresponding query takes parameters, and must
be a parameter object returned by Query.createParameterList()
created by the corresponding query.handler
- a ResultHandler responsible for handling results generated
by this querymaxRows
- the maximum number of rows to retrievefetchSize
- if QUERY_FORWARD_CURSOR is set, the preferred number of rows to retrieve before suspendingflags
- a combination of QUERY_* flags indicating how to handle the query.SQLException
- if query execution failsvoid fetch(ResultCursor cursor, ResultHandler handler, int fetchSize) throws SQLException
cursor
- the cursor to fetch fromhandler
- the handler to feed results tofetchSize
- the preferred number of rows to retrieve before suspendingSQLException
- if query execution failsQuery createSimpleQuery(String sql)
Query.createParameterList()
of the returned object will
always return an empty ParameterList.sql
- the SQL for the query to createQuery createParameterizedQuery(String sql)
Query.createParameterList()
of the returned object will
create an appropriately-sized ParameterList.sql
- the SQL for the query to create, with '?' placeholders for
parameters.void processNotifies() throws SQLException
SQLException
- if and error occurs while fetching notificationsParameterList createFastpathParameters(int count)
fastpathCall(int, org.postgresql.core.ParameterList, boolean)
.count
- the number of parameters the fastpath call will takefastpathCall(int, org.postgresql.core.ParameterList, boolean)
.byte[] fastpathCall(int fnid, ParameterList params, boolean suppressBegin) throws SQLException
fnid
- the OID of the backend function to invokeparams
- a ParameterList returned from createFastpathParameters(int)
containing the parameters to pass to the backend functionsuppressBegin
- if begin should be suppressednull
if a void result was returnedSQLException
- if an error occurs while executing the fastpath callCopyOperation startCopy(String sql, boolean suppressBegin) throws SQLException
sql
- input sqlsuppressBegin
- if begin should be suppressedSQLException
- when initializing the given query failsCopyright © 2016 PostgreSQL Global Development Group. All rights reserved.