org.postgresql.core
Interface QueryExecutor

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

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

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.

Parameters:

timeoutMillis - number of milliseconds to block for

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.