com.impossibl.postgres.protocol

Interface RequestExecutor

public interface RequestExecutor

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	RequestExecutor.CopyFromHandler Copy In & Out
static interface	RequestExecutor.CopyToHandler
static interface	RequestExecutor.ErrorHandler Base type handler for all requests.
static interface	RequestExecutor.ExecuteHandler Request handler interface for the execute(String, String, FieldFormatRef[], ByteBuf[], FieldFormatRef[], int, ExecuteHandler) request.
static interface	RequestExecutor.ExtendedQueryHandler Request handler interface for the query(String, String, FieldFormatRef[], ByteBuf[], FieldFormatRef[], int, ExtendedQueryHandler) request.
static interface	RequestExecutor.FunctionCallHandler Request handler interface for the call(int, FieldFormatRef[], ByteBuf[], FunctionCallHandler) request.
static interface	RequestExecutor.NotificationHandler Asynchronous Notification
static interface	RequestExecutor.PrepareHandler Request handler interface for th `prepare(sql,statementName,parameterTypes,PrepareHandler)` request.
static interface	RequestExecutor.QueryHandler Request handler interface for the query(String, QueryHandler) request.
static interface	RequestExecutor.ResumeHandler Request handler interface for the resume(String, int, ResumeHandler) request.
static interface	RequestExecutor.SynchronizedHandler Base type handler for requests that may receive a ready callback containing a transaction status.

Method Summary

Modifier and Type	Method and Description
void	call(int functionId, FieldFormatRef[] parameterFormats, io.netty.buffer.ByteBuf[] parameterBuffers, RequestExecutor.FunctionCallHandler handler) Invokes the function specified by functionId and returns its results.
void	close(ServerObjectType serverObjectType, String objectName) Closes a previously prepared statement for the connection.
void	copyFrom(String sql, InputStream stream, RequestExecutor.CopyFromHandler handler)
void	copyTo(String sql, OutputStream stream, RequestExecutor.CopyToHandler handler)
void	execute(String portalName, String statementName, FieldFormatRef[] parameterFormats, io.netty.buffer.ByteBuf[] parameterBuffers, FieldFormatRef[] resultFieldFormats, int maxRows, RequestExecutor.ExecuteHandler handler) Uses the "extended" query protocol to execute a previously prepared query.
void	finish(String portalName, RequestExecutor.SynchronizedHandler handler) Closes a portal that was previously suspended and synchronizes the transaction state.
void	lazyExecute(String statementName) Executes a statement at the earliest convenience.
void	prepare(String statementName, String sqlText, TypeRef[] parameterTypes, RequestExecutor.PrepareHandler handler) Prepares a query for later, possibly repeated, execution via the execute(String, String, FieldFormatRef[], ByteBuf[], FieldFormatRef[], int, ExecuteHandler) request.
void	query(String sql, RequestExecutor.QueryHandler handler) Uses the "simple" query protocol to execute the given query.
void	query(String sql, String portalName, FieldFormatRef[] parameterFormats, io.netty.buffer.ByteBuf[] parameterBuffers, FieldFormatRef[] resultFieldFormats, int maxRows, RequestExecutor.ExtendedQueryHandler handler) Uses the "extended" query protocol to execute the given query.
void	resume(String portalName, int maxRows, RequestExecutor.ResumeHandler handler) Resumes a portal previously instantiated via an execute(String, String, FieldFormatRef[], ByteBuf[], FieldFormatRef[], int, ExecuteHandler) or query(String, String, FieldFormatRef[], ByteBuf[], FieldFormatRef[], int, ExtendedQueryHandler) request.

Method Detail

query

void query(String sql,
           RequestExecutor.QueryHandler handler)
    throws IOException

Uses the "simple" query protocol to execute the given query. The SQL provided may contain multiple queries concatenated with a semi-colon. Each separate query will produce a single RequestExecutor.QueryHandler.handleComplete(String, Long, Long, TypeRef[], ResultField[], RowDataSet, List)` or RequestExecutor.ErrorHandler.handleError(Throwable, List) callback in the provided handler. After all queries have been completed a RequestExecutor.SynchronizedHandler.handleReady(TransactionStatus) is issued.

Parameters:

sql - SQL query or queries to execute.

handler - Query handler to process results. Can produce multiple RequestExecutor.QueryHandler.handleComplete(String, Long, Long, TypeRef[], ResultField[], RowDataSet, List) or RequestExecutor.ErrorHandler.handleError(Throwable, List) callbacks. Followed by a final RequestExecutor.SynchronizedHandler.handleReady(TransactionStatus) callback when all requests are complete.

Throws:

IOException - If an error occurs submitting the request.

query

void query(String sql,
           String portalName,
           FieldFormatRef[] parameterFormats,
           io.netty.buffer.ByteBuf[] parameterBuffers,
           FieldFormatRef[] resultFieldFormats,
           int maxRows,
           RequestExecutor.ExtendedQueryHandler handler)
    throws IOException

Uses the "extended" query protocol to execute the given query. The requests can pass parameters and result formats. The SQL can only contain a single SQL query and thus the will only produce a single RequestExecutor.QueryHandler.handleComplete(String, Long, Long, TypeRef[], ResultField[], RowDataSet, List), RequestExecutor.ExtendedQueryHandler.handleSuspend(TypeRef[], ResultField[], RowDataSet, List) or RequestExecutor.ErrorHandler.handleError(Throwable, List) callback, followed by a final RequestExecutor.SynchronizedHandler.handleReady(TransactionStatus). Setting maxRows to anything greater than zero enables suspend/resume functionality via portals. Results are delivered in groups of maxRows via the RequestExecutor.ExtendedQueryHandler.handleSuspend(TypeRef[], ResultField[], RowDataSet, List) callback. After the first group is received the resume(String, int, ResumeHandler) request can be used to receive the next group of rows. A unique portalName is required if you wish to have multiple portals open simultaneously. If not, you can pass null and an unnamed portal will be used; it will destroy any current use of that portal. Anytime a named portal is used it must be finalized with a close(ServerObjectType, String) or finish(String, SynchronizedHandler) request.

Parameters:

sql - SQL query to execute.

portalName - Name of the portal to instantiate or null to use the unnamed portal.

parameterFormats - Formats (text or binary) of parameters in `parameterBuffers`. Must match the number of `parameterBuffers` provided.

parameterBuffers - Buffer of encoded parameter values.

resultFieldFormats - Desired formats of the result fields. Passing an empty array will request all binary format parameters. Passing any number of formats less than the number of result fields will cause the last format provided to be repeated.

maxRows - The number of results to receive at a time, or zero to receive all results at once. Anything other than zero instantiates a portal.

handler - Query handler to process results. Will produce a single RequestExecutor.QueryHandler.handleComplete(String, Long, Long, TypeRef[], ResultField[], RowDataSet, List), RequestExecutor.ExtendedQueryHandler.handleSuspend(TypeRef[], ResultField[], RowDataSet, List) or RequestExecutor.ErrorHandler.handleError(Throwable, List) callback.

Throws:

IOException - If an error occurs submitting the request.

prepare

void prepare(String statementName,
             String sqlText,
             TypeRef[] parameterTypes,
             RequestExecutor.PrepareHandler handler)
      throws IOException

Prepares a query for later, possibly repeated, execution via the execute(String, String, FieldFormatRef[], ByteBuf[], FieldFormatRef[], int, ExecuteHandler) request. The SQL can only contain a single SQL query. Any text that contains multiple queries will be rejected with an error. If statementName is provided the query will be saved with that name and can be executed repeatedly until it is closed. If null is provided as the statement name it will save it under the "unnamed" statement and can be used until another prepare request is made using the "unnamed" statement. All named statements should be closed via a close(ServerObjectType, String) request when they are no longer in use. parameterTypes directs the server on what types of parameters are intended to correspond to parameter placeholders in the SQL text. One or all parameter types can be omitted by passing less than the number of parameters in the query or passing null as the parameter type. The server will attempt to infer the proper type for any parameters without provided types.

Parameters:

sqlText - SQL text to parse; containing a maximum of one query.

statementName - Name of the to-be-parsed sql or null to use the unnamed statement. All named statements should be closed when no longer in use.

parameterTypes - Parameter types corresponding to parameters placeholders in the query string.

handler - Handler to process results of the request. Will produce a single RequestExecutor.PrepareHandler.handleComplete(TypeRef[], ResultField[], List) or RequestExecutor.ErrorHandler.handleError(Throwable, List) callback.

Throws:

IOException - If an error occurs submitting the request.

execute

void execute(String portalName,
             String statementName,
             FieldFormatRef[] parameterFormats,
             io.netty.buffer.ByteBuf[] parameterBuffers,
             FieldFormatRef[] resultFieldFormats,
             int maxRows,
             RequestExecutor.ExecuteHandler handler)
      throws IOException

Uses the "extended" query protocol to execute a previously prepared query. The requests can pass parameters and result formats. Setting maxRows to anything greater than zero enables suspend/resume functionality via portals. Results are delivered in groups of maxRows via the RequestExecutor.ExtendedQueryHandler.handleSuspend(TypeRef[], ResultField[], RowDataSet, List) callback. After the first group is received the resume(String, int, ResumeHandler) request can be used to receive the next group of rows. A unique portalName is required if you wish to have multiple portals open and suspended simultaneously. If not, you can pass null and an unnamed portal will be used; it will destroy any current use of that portal. Anytime a named portal is used it must be finalized with a close(ServerObjectType, String) or finish(String, SynchronizedHandler) request.

Parameters:

portalName - Name of the portal to instantiate or null to use the unnamed portal.

statementName - Name of the statement to execute or null to execute the unnamed statement.

parameterFormats - Formats (text or binary) of parameters in `parameterBuffers`. Must match the number of `parameterBuffers` provided.

parameterBuffers - Buffer of encoded parameter values.

resultFieldFormats - Desired formats of the result fields. Passing an empty array will request all binary format parameters. Passing any number of formats less than the number of result fields will cause the last format provided to be repeated.

maxRows - The number of results to receive at a time, or zero to receive all results at once. Anything other than zero instantiates a portal.

handler - Execute handler to process results. Will produce a single RequestExecutor.ResumeHandler.handleComplete(String, Long, Long, RowDataSet, List), RequestExecutor.ErrorHandler.handleError(Throwable, List) callback, followed by a final RequestExecutor.SynchronizedHandler.handleReady(TransactionStatus) for completed queries. Alternatively, for suspended queries, you will receive a single RequestExecutor.ResumeHandler.handleSuspend(RowDataSet, List) callback.

Throws:

IOException - If an error occurs submitting the request.

resume

void resume(String portalName,
            int maxRows,
            RequestExecutor.ResumeHandler handler)
     throws IOException

Resumes a portal previously instantiated via an execute(String, String, FieldFormatRef[], ByteBuf[], FieldFormatRef[], int, ExecuteHandler) or query(String, String, FieldFormatRef[], ByteBuf[], FieldFormatRef[], int, ExtendedQueryHandler) request. A portal can be resumed until no more rows are available. As long as more rows are available the request will complete with a RequestExecutor.ResumeHandler.handleSuspend(RowDataSet, List) callback. When no more rows are available the request will complete with a RequestExecutor.ResumeHandler.handleComplete(String, Long, Long, RowDataSet, List) callback. Of particular note is that this request is not synchronized. Its handler does not extend RequestExecutor.SynchronizedHandler), thus will not receive a ready callback.

Parameters:

portalName - Name of the portal to resume or null to resume the unnamed portal.

maxRows - Max number of rows to return from this request.

handler - Execute handler to process results. Will produce a single RequestExecutor.ResumeHandler.handleComplete(String, Long, Long, RowDataSet, List), RequestExecutor.ResumeHandler.handleSuspend(RowDataSet, List) or RequestExecutor.ErrorHandler.handleError(Throwable, List) callback.

Throws:

IOException - If an error occurs submitting the request.

finish

void finish(String portalName,
            RequestExecutor.SynchronizedHandler handler)
     throws IOException

Closes a portal that was previously suspended and synchronizes the transaction state. This can be used in place of a close(ServerObjectType, String) request to allow waiting for the requests completion and synchronization.

Parameters:

portalName - Name of a previously executed, and suspended, portal.

handler - Handler to process synchronization callback.

Throws:

IOException - If an error occurs submitting the request.

call

void call(int functionId,
          FieldFormatRef[] parameterFormats,
          io.netty.buffer.ByteBuf[] parameterBuffers,
          RequestExecutor.FunctionCallHandler handler)
   throws IOException

Invokes the function specified by functionId and returns its results. This request is essentially deprecated by PostgreSQL and included here for completeness.

Parameters:

functionId - Function to invoke; specified by its OID.

parameterFormats - Formats (text or binary) of parameters in `parameterBuffers`. Must match the number of `parameterBuffers` provided.

parameterBuffers - Buffer of encoded parameter values.

handler - Function call handler to process results. Will produce a single RequestExecutor.FunctionCallHandler.handleComplete(ByteBuf, List) or RequestExecutor.ErrorHandler.handleError(Throwable, List) callback.

Throws:

IOException - If an error occurs submitting the request.

close

void close(ServerObjectType serverObjectType,
           String objectName)
    throws IOException

Closes a previously prepared statement for the connection.

Parameters:

objectName - Name of the object to close.

Throws:

IOException - If an error occurs submitting the request.

lazyExecute

void lazyExecute(String statementName)
          throws IOException

Executes a statement at the earliest convenience. The submitter has no ability to wait for or monitor the status of the request. All notices and errors are reported to whatever request handler is submitted after it. The best example of using this is beginning a transaction. The request can be sent and will be reported on the following request; including errors that would stop the following request from executing. Although it uses bind/execute, it currently doesn't support passing parameters to the bind, nor receiving any results from a response.

Parameters:

statementName - Name of statement to execute.

Throws:

IOException - If an error occurs submitting the request.

copyFrom

void copyFrom(String sql,
              InputStream stream,
              RequestExecutor.CopyFromHandler handler)
       throws IOException

Throws:

IOException

copyTo

void copyTo(String sql,
            OutputStream stream,
            RequestExecutor.CopyToHandler handler)
     throws IOException

Throws:

IOException