QueryExecutor (PostgreSQL JDBC Driver

All Superinterfaces:

TypeTransferModeRegistry

All Known Implementing Classes:

QueryExecutorBase, QueryExecutorImpl
```
public interface QueryExecutor
extends TypeTransferModeRegistry
```
Abstracts the protocol-specific details of executing a query.
Every connection has a single QueryExecutor implementation associated with it. This object provides:
- factory methods for Query objects (createSimpleQuery(String) and createQuery(String, boolean, boolean, String...))
- execution methods for created Query objects ( execute(Query, ParameterList, ResultHandler, int, int, int) for single queries and execute(Query[], ParameterList[], BatchResultHandler, int, int, int) for batches of queries)
- a fastpath call interface (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.
Author:

Oliver Jowett ([email protected])

Field Summary

Fields
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_EXECUTE_AS_SIMPLE` Execute the query via simple 'Q' command (not parse, bind, exec, but simple execute).
`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.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`abort()` Abort at network level without sending the Terminate message to the backend.
`CachedQuery`	`borrowCallableQuery(String sql)`
`CachedQuery`	`borrowQuery(String sql)`
`CachedQuery`	`borrowQueryByKey(Object key)`
`CachedQuery`	`borrowReturningQuery(String sql, String[] columnNames)`
`void`	`close()` Close this connection cleanly.
`ParameterList`	`createFastpathParameters(int count)` Create a new ParameterList implementation suitable for invoking a fastpath function via `fastpathCall(int, org.postgresql.core.ParameterList, boolean)`.
`CachedQuery`	`createQuery(String sql, boolean escapeProcessing, boolean isParameterized, String... columnNames)`
`CachedQuery`	`createQueryByKey(Object key)`
`Object`	`createQueryKey(String sql, boolean escapeProcessing, boolean isParameterized, String... columnNames)`
`Query`	`createSimpleQuery(String sql)` Create an unparameterized Query object suitable for execution by this QueryExecutor.
`void`	`execute(Query[] queries, ParameterList[] parameterLists, BatchResultHandler 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.
`String`	`getApplicationName()` Returns application_name connection property.
`AutoSave`	`getAutoSave()`
`int`	`getBackendPID()` Return the process ID (PID) of the backend server process handling this connection.
`String`	`getDatabase()`
`Encoding`	`getEncoding()`
`HostSpec`	`getHostSpec()`
`boolean`	`getIntegerDateTimes()` Returns true if server uses integer instead of double for binary date and time encodings.
`PGNotification[]`	`getNotifications()` Retrieve and clear the set of asynchronous notifications pending on this connection.
`PreferQueryMode`	`getPreferQueryMode()`
`int`	`getProtocolVersion()`
`ReplicationProtocol`	`getReplicationProtocol()`
`String`	`getServerVersion()` Return the server version from the server_version GUC.
`int`	`getServerVersionNum()` Get a machine-readable server version.
`boolean`	`getStandardConformingStrings()` Returns whether the server treats string-literals according to the SQL standard or if it uses traditional PostgreSQL escaping rules.
`TimeZone`	`getTimeZone()` Returns backend timezone in java format.
`TransactionState`	`getTransactionState()` Get the current transaction state of this connection.
`String`	`getUser()`
`SQLWarning`	`getWarnings()` Retrieve and clear the chain of warnings accumulated on this connection.
`boolean`	`isClosed()` Check if this connection is closed.
`boolean`	`isColumnSanitiserDisabled()`
`boolean`	`isReWriteBatchedInsertsEnabled()`
`void`	`processNotifies()` Prior to attempting to retrieve notifications, we need to pull any recently received notifications off of the network buffers.
`void`	`processNotifies(int timeoutMillis)` Prior to attempting to retrieve notifications, we need to pull any recently received notifications off of the network buffers.
`void`	`releaseQuery(CachedQuery cachedQuery)`
`void`	`sendQueryCancel()` Sends a query cancellation for this connection.
`void`	`setAutoSave(AutoSave autoSave)`
`void`	`setBinaryReceiveOids(Set<Integer> useBinaryForOids)` Sets the oids that should be received using binary encoding.
`void`	`setBinarySendOids(Set<Integer> useBinaryForOids)` Sets the oids that should be sent using binary encoding.
`void`	`setFlushCacheOnDeallocate(boolean flushCacheOnDeallocate)` By default, the connection resets statement cache in case deallocate all/discard all message is observed.
`CopyOperation`	`startCopy(String sql, boolean suppressBegin)` Issues a COPY FROM STDIN / COPY TO STDOUT statement and returns handler for associated operation.
`boolean`	`willHealOnRetry(SQLException e)`
`Query`	`wrap(List<NativeQuery> queries)` Wrap given native query into a ready for execution format

Methods inherited from interface org.postgresql.core.v3.TypeTransferModeRegistry
useBinaryForReceive, useBinaryForSend

- Field Detail
  - QUERY_ONESHOT
```
static final int QUERY_ONESHOT
```
    Flag for query execution that indicates the given Query object is unlikely to be reused.
    
    See Also:
    
    Constant Field Values
  - QUERY_NO_METADATA
```
static final int QUERY_NO_METADATA
```
    Flag for query execution that indicates that resultset metadata isn't needed and can be safely omitted.
    
    See Also:
    
    Constant Field Values
  - QUERY_NO_RESULTS
```
static final 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).
    
    See Also:
    
    Constant Field Values
  - QUERY_FORWARD_CURSOR
```
static final int QUERY_FORWARD_CURSOR
```
    Flag for query execution that indicates a forward-fetch-capable cursor should be used if possible.
    
    See Also:
    
    Constant Field Values
  - QUERY_SUPPRESS_BEGIN
```
static final 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.
    
    See Also:
    
    Constant Field Values
  - QUERY_DESCRIBE_ONLY
```
static final 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.
    
    See Also:
    
    Constant Field Values
  - QUERY_BOTH_ROWS_AND_STATUS
```
static final 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.
    
    See Also:
    
    Constant Field Values
  - QUERY_FORCE_DESCRIBE_PORTAL
```
static final int QUERY_FORCE_DESCRIBE_PORTAL
```
    Force this query to be described at each execution. This is done in pipelined batches where we might need to detect mismatched result types.
    
    See Also:
    
    Constant Field Values
  - QUERY_DISALLOW_BATCHING
```
@Deprecated
static final int QUERY_DISALLOW_BATCHING
```
    Deprecated. in PgJDBC 9.4 as we now auto-size batches.
    
    Flag to disable batch execution when we expect results (generated keys) from a statement.
    
    See Also:
    
    Constant Field Values
  - QUERY_NO_BINARY_TRANSFER
```
static final int QUERY_NO_BINARY_TRANSFER
```
    Flag for query execution to avoid using binary transfer.
    
    See Also:
    
    Constant Field Values
  - QUERY_EXECUTE_AS_SIMPLE
```
static final int QUERY_EXECUTE_AS_SIMPLE
```
    Execute the query via simple 'Q' command (not parse, bind, exec, but simple execute). This sends query text on each execution, however it supports sending multiple queries separated with ';' as a single command.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - execute
```
void execute(Query query,
             ParameterList parameters,
             ResultHandler handler,
             int maxRows,
             int fetchSize,
             int flags)
      throws SQLException
```
    Execute a Query, passing results to a provided ResultHandler.
    
    Parameters:
    
    query - the query to execute; must be a query returned from calling wrap(List) 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 query
    
    maxRows - the maximum number of rows to retrieve
    
    fetchSize - if QUERY_FORWARD_CURSOR is set, the preferred number of rows to retrieve before suspending
    
    flags - a combination of QUERY_* flags indicating how to handle the query.
    
    Throws:
    
    SQLException - if query execution fails
  - execute
```
void execute(Query[] queries,
             ParameterList[] parameterLists,
             BatchResultHandler handler,
             int maxRows,
             int fetchSize,
             int flags)
      throws SQLException
```
    Execute several Query, passing results to a provided ResultHandler.
    
    Parameters:
    
    queries - the queries to execute; each must be a query returned from calling wrap(List) 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 query
    
    maxRows - the maximum number of rows to retrieve
    
    fetchSize - if QUERY_FORWARD_CURSOR is set, the preferred number of rows to retrieve before suspending
    
    flags - a combination of QUERY_* flags indicating how to handle the query.
    
    Throws:
    
    SQLException - if query execution fails
  - fetch
```
void fetch(ResultCursor cursor,
           ResultHandler handler,
           int fetchSize)
    throws SQLException
```
    Fetch additional rows from a cursor.
    
    Parameters:
    
    cursor - the cursor to fetch from
    
    handler - the handler to feed results to
    
    fetchSize - the preferred number of rows to retrieve before suspending
    
    Throws:
    
    SQLException - if query execution fails
  - createSimpleQuery
```
Query createSimpleQuery(String sql)
                 throws SQLException
```
    Create an unparameterized Query object suitable for execution by this QueryExecutor. The provided query string is not parsed for parameter placeholders ('?' characters), and the Query.createParameterList() of the returned object will always return an empty ParameterList.
    
    Parameters:
    
    sql - the SQL for the query to create
    
    Returns:
    
    a new Query object
    
    Throws:
    
    SQLException - if something goes wrong
  - isReWriteBatchedInsertsEnabled
```
boolean isReWriteBatchedInsertsEnabled()
```
  - createQuery
```
CachedQuery createQuery(String sql,
                        boolean escapeProcessing,
                        boolean isParameterized,
                        String... columnNames)
                 throws SQLException
```
    Throws:
    
    SQLException
  - createQueryKey
```
Object createQueryKey(String sql,
                      boolean escapeProcessing,
                      boolean isParameterized,
                      String... columnNames)
```
  - createQueryByKey
```
CachedQuery createQueryByKey(Object key)
                      throws SQLException
```
    Throws:
    
    SQLException
  - borrowQueryByKey
```
CachedQuery borrowQueryByKey(Object key)
                      throws SQLException
```
    Throws:
    
    SQLException
  - borrowQuery
```
CachedQuery borrowQuery(String sql)
                 throws SQLException
```
    Throws:
    
    SQLException
  - borrowCallableQuery
```
CachedQuery borrowCallableQuery(String sql)
                         throws SQLException
```
    Throws:
    
    SQLException
  - borrowReturningQuery
```
CachedQuery borrowReturningQuery(String sql,
                                 String[] columnNames)
                          throws SQLException
```
    Throws:
    
    SQLException
  - releaseQuery
```
void releaseQuery(CachedQuery cachedQuery)
```
  - wrap
```
Query wrap(List<NativeQuery> queries)
```
    Wrap given native query into a ready for execution format
    
    Parameters:
    
    queries - list of queries in native to database syntax
    
    Returns:
    
    query object ready for execution by this query executor
  - processNotifies
```
void processNotifies()
              throws SQLException
```
    Prior to attempting to retrieve notifications, we need to pull any recently received notifications off of the network buffers. The notification retrieval in ProtocolConnection cannot do this as it is prone to deadlock, so the higher level caller must be responsible which requires exposing this method.
    
    Throws:
    
    SQLException - if and error occurs while fetching notifications
  - processNotifies
```
void processNotifies(int timeoutMillis)
              throws SQLException
```
    Prior to attempting to retrieve notifications, we need to pull any recently received notifications off of the network buffers. The notification retrieval in ProtocolConnection cannot do this as it is prone to deadlock, so the higher level caller must be responsible which requires exposing this method. This variant supports blocking for the given time in millis.
    
    Throws:
    
    SQLException - if and error occurs while fetching notifications
  - createFastpathParameters
```
ParameterList createFastpathParameters(int count)
```
    Create a new ParameterList implementation suitable for invoking a fastpath function via fastpathCall(int, org.postgresql.core.ParameterList, boolean).
    
    Parameters:
    
    count - the number of parameters the fastpath call will take
    
    Returns:
    
    a ParameterList suitable for passing to fastpathCall(int, org.postgresql.core.ParameterList, boolean).
  - fastpathCall
```
byte[] fastpathCall(int fnid,
                    ParameterList params,
                    boolean suppressBegin)
             throws SQLException
```
    Invoke a backend function via the fastpath interface.
    
    Parameters:
    
    fnid - the OID of the backend function to invoke
    
    params - a ParameterList returned from createFastpathParameters(int) containing the parameters to pass to the backend function
    
    suppressBegin - if begin should be suppressed
    
    Returns:
    
    the binary-format result of the fastpath call, or null if a void result was returned
    
    Throws:
    
    SQLException - if an error occurs while executing the fastpath call
  - startCopy
```
CopyOperation startCopy(String sql,
                        boolean suppressBegin)
                 throws SQLException
```
    Issues a COPY FROM STDIN / COPY TO STDOUT statement and returns handler for associated operation. Until the copy operation completes, no other database operation may be performed. Implemented for protocol version 3 only.
    
    Parameters:
    
    sql - input sql
    
    suppressBegin - if begin should be suppressed
    
    Returns:
    
    handler for associated operation
    
    Throws:
    
    SQLException - when initializing the given query fails
  - getProtocolVersion
```
int getProtocolVersion()
```
    Returns:
    
    the version of the implementation
  - setBinaryReceiveOids
```
void setBinaryReceiveOids(Set<Integer> useBinaryForOids)
```
    Sets the oids that should be received using binary encoding.
    
    Parameters:
    
    useBinaryForOids - The oids to request with binary encoding.
  - setBinarySendOids
```
void setBinarySendOids(Set<Integer> useBinaryForOids)
```
    Sets the oids that should be sent using binary encoding.
    
    Parameters:
    
    useBinaryForOids - The oids to send with binary encoding.
  - getIntegerDateTimes
```
boolean getIntegerDateTimes()
```
    Returns true if server uses integer instead of double for binary date and time encodings.
    
    Returns:
    
    the server integer_datetime setting.
  - getHostSpec
```
HostSpec getHostSpec()
```
    Returns:
    
    the host and port this connection is connected to.
  - getUser
```
String getUser()
```
    Returns:
    
    the user this connection authenticated as.
  - getDatabase
```
String getDatabase()
```
    Returns:
    
    the database this connection is connected to.
  - sendQueryCancel
```
void sendQueryCancel()
              throws SQLException
```
    Sends a query cancellation for this connection.
    
    Throws:
    
    SQLException - if something goes wrong.
  - getBackendPID
```
int getBackendPID()
```
    Return the process ID (PID) of the backend server process handling this connection.
    
    Returns:
    
    process ID (PID) of the backend server process handling this connection
  - abort
```
void abort()
```
    Abort at network level without sending the Terminate message to the backend.
  - close
```
void close()
```
    Close this connection cleanly.
  - isClosed
```
boolean isClosed()
```
    Check if this connection is closed.
    
    Returns:
    
    true iff the connection is closed.
  - getServerVersion
```
String getServerVersion()
```
    Return the server version from the server_version GUC. Note that there's no requirement for this to be numeric or of the form x.y.z. PostgreSQL development releases usually have the format x.ydevel e.g. 9.4devel; betas usually x.ybetan e.g. 9.4beta1. The --with-extra-version configure option may add an arbitrary string to this. Don't use this string for logic, only use it when displaying the server version to the user. Prefer getServerVersionNum() for all logic purposes.
    
    Returns:
    
    the server version string from the server_version guc
  - getNotifications
```
PGNotification[] getNotifications()
                           throws SQLException
```
    Retrieve and clear the set of asynchronous notifications pending on this connection.
    
    Returns:
    
    an array of notifications; if there are no notifications, an empty array is returned.
    
    Throws:
    
    SQLException - if and error occurs while fetching notifications
  - getWarnings
```
SQLWarning getWarnings()
```
    Retrieve and clear the chain of warnings accumulated on this connection.
    
    Returns:
    
    the first SQLWarning in the chain; subsequent warnings can be found via SQLWarning.getNextWarning().
  - getServerVersionNum
```
int getServerVersionNum()
```
    Get a machine-readable server version. This returns the value of the server_version_num GUC. If no such GUC exists, it falls back on attempting to parse the text server version for the major version. If there's no minor version (e.g. a devel or beta release) then the minor version is set to zero. If the version could not be parsed, zero is returned.
    
    Returns:
    
    the server version in numeric XXYYZZ form, eg 090401, from server_version_num
  - getTransactionState
```
TransactionState getTransactionState()
```
    Get the current transaction state of this connection.
    
    Returns:
    
    a ProtocolConnection.TRANSACTION_* constant.
  - getStandardConformingStrings
```
boolean getStandardConformingStrings()
```
    Returns whether the server treats string-literals according to the SQL standard or if it uses traditional PostgreSQL escaping rules. Versions up to 8.1 always treated backslashes as escape characters in string-literals. Since 8.2, this depends on the value of the standard_conforming_strings server variable.
    
    Returns:
    
    true if the server treats string literals according to the SQL standard
  - getTimeZone
```
TimeZone getTimeZone()
```
    Returns backend timezone in java format.
    
    Returns:
    
    backend timezone in java format.
  - getEncoding
```
Encoding getEncoding()
```
    Returns:
    
    the current encoding in use by this connection
  - getApplicationName
```
String getApplicationName()
```
    Returns application_name connection property.
    
    Returns:
    
    application_name connection property
  - isColumnSanitiserDisabled
```
boolean isColumnSanitiserDisabled()
```
  - getPreferQueryMode
```
PreferQueryMode getPreferQueryMode()
```
  - getAutoSave
```
AutoSave getAutoSave()
```
  - setAutoSave
```
void setAutoSave(AutoSave autoSave)
```
  - willHealOnRetry
```
boolean willHealOnRetry(SQLException e)
```
  - setFlushCacheOnDeallocate
```
void setFlushCacheOnDeallocate(boolean flushCacheOnDeallocate)
```
    By default, the connection resets statement cache in case deallocate all/discard all message is observed. This API allows to disable that feature for testing purposes.
    
    Parameters:
    
    flushCacheOnDeallocate - true if statement cache should be reset when "deallocate/discard" message observed
  - getReplicationProtocol
```
ReplicationProtocol getReplicationProtocol()
```
    Returns:
    
    the ReplicationProtocol instance for this connection.

Interface QueryExecutor

Field Summary

Method Summary

Methods inherited from interface org.postgresql.core.v3.TypeTransferModeRegistry

Field Detail

QUERY_ONESHOT

QUERY_NO_METADATA

QUERY_NO_RESULTS

QUERY_FORWARD_CURSOR

QUERY_SUPPRESS_BEGIN

QUERY_DESCRIBE_ONLY

QUERY_BOTH_ROWS_AND_STATUS

QUERY_FORCE_DESCRIBE_PORTAL

QUERY_DISALLOW_BATCHING

QUERY_NO_BINARY_TRANSFER

QUERY_EXECUTE_AS_SIMPLE

Method Detail

execute

execute

fetch

createSimpleQuery

isReWriteBatchedInsertsEnabled

createQuery

createQueryKey

createQueryByKey

borrowQueryByKey

borrowQuery

borrowCallableQuery

borrowReturningQuery

releaseQuery

wrap

processNotifies

processNotifies

createFastpathParameters

fastpathCall

startCopy

getProtocolVersion

setBinaryReceiveOids

setBinarySendOids

getIntegerDateTimes

getHostSpec

getUser

getDatabase

sendQueryCancel

getBackendPID

abort

close

isClosed

getServerVersion

getNotifications

getWarnings

getServerVersionNum

getTransactionState

getStandardConformingStrings

getTimeZone

getEncoding

getApplicationName

isColumnSanitiserDisabled

getPreferQueryMode

getAutoSave

setAutoSave

willHealOnRetry

setFlushCacheOnDeallocate

getReplicationProtocol