org.firebirdsql.gds.ng.wire.FbWireOperations Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of jaybird-jdk17 Show documentation
Show all versions of jaybird-jdk17 Show documentation
JDBC Driver for the Firebird RDBMS
/*
* Firebird Open Source JavaEE Connector - JDBC Driver
*
* Distributable under LGPL license.
* You may obtain a copy of the License at http://www.gnu.org/copyleft/lgpl.html
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* LGPL License for more details.
*
* This file was created by members of the firebird development team.
* All individual contributions remain the Copyright (C) of those
* individuals. Contributors to this file are either listed here or
* can be obtained from a source control history command.
*
* All rights reserved.
*/
package org.firebirdsql.gds.ng.wire;
import org.firebirdsql.gds.ng.WarningMessageCallback;
import org.firebirdsql.gds.ng.dbcrypt.DbCryptCallback;
import java.io.IOException;
import java.sql.SQLException;
/**
* Common connection operations shared by database and service handles
*
* @author Mark Rotteveel
* @since 3.0
*/
public interface FbWireOperations {
/**
* @return Instance of {@link XdrStreamAccess} for this service.
*/
XdrStreamAccess getXdrStreamAccess();
/**
* Process the status vector and returns the associated {@link SQLException}
* instance.
*
* NOTE: This method returns the SQLException read from the
* status vector, and only throws SQLException when an error occurs
* processing the status ector.
*
*
* @return SQLException from the status vector
* @throws SQLException
* for errors reading or processing the status vector
*/
SQLException readStatusVector() throws SQLException;
/**
* Reads the response from the server.
*
* @param callback
* Callback object for warnings, null for default callback
* @return {@link Response} read.
* @throws SQLException
* For errors returned from the server, or when attempting to read
* @throws IOException
* For errors reading the response from the connection.
*/
Response readResponse(WarningMessageCallback callback) throws SQLException, IOException;
/**
* Reads the response from the server when the operation code has already been read.
*
* @param operationCode
* The operation code
* @param callback
* Callback object for warnings, null for default callback
* @return {@link Response} read.
* @throws SQLException
* For errors returned from the server, or when attempting to read
* @throws IOException
* For errors reading the response from the connection.
* @see #readResponse(WarningMessageCallback)
*/
Response readOperationResponse(int operationCode, WarningMessageCallback callback) throws SQLException, IOException;
/**
* Convenience method to read a Response to a GenericResponse
*
* @param callback
* Callback object for warnings, null for default callback
* @return GenericResponse
* @throws SQLException
* For errors returned from the server, or when attempting to
* read.
* @throws IOException
* For errors reading the response from the connection.
*/
GenericResponse readGenericResponse(WarningMessageCallback callback) throws SQLException, IOException;
/**
* Convenience method to read a Response to a SqlResponse
*
* @param callback
* Callback object for warnings, null for default callback
* @return SqlResponse
* @throws SQLException
* For errors returned from the server, or when attempting to
* read.
* @throws IOException
* For errors reading the response from the connection.
*/
SqlResponse readSqlResponse(WarningMessageCallback callback) throws SQLException, IOException;
/**
* Enqueue a deferred action.
*
* FbDatabase implementations that do not support deferred actions are allowed to throw an
* {@link java.lang.UnsupportedOperationException}
*
*
* @param deferredAction
* Deferred action
*/
void enqueueDeferredAction(DeferredAction deferredAction);
/**
* Consumes packets notifying for warnings, but ignoring exceptions thrown from the packet.
*
* This method should only be used inside the implementation if either packets need to be ignored,
* or to ensure that there is no backlog of packets (eg when an exception occurs during processing of multiple
* package responses).
*
*
* @param numberOfResponses
* Number of responses to consume.
* @param warningCallback
* Callback for warnings
*/
void consumePackets(int numberOfResponses, WarningMessageCallback warningCallback);
/**
* Processes any deferred actions. Protocol versions that do not support deferred actions should simply do nothing.
*/
void processDeferredActions();
/**
* Reads the response from the server.
*
* @param warningCallback
* Callback object for signalling warnings, null to register warning on the default callback
* @return Response
* @throws SQLException
* For errors returned from the server, or when attempting to
* read
* @throws IOException
* For errors reading the response from the connection.
*/
Response readSingleResponse(WarningMessageCallback warningCallback) throws SQLException, IOException;
/**
* @param response
* Response to process
* @throws java.sql.SQLException
* For errors returned from the server.
*/
void processResponse(Response response) throws SQLException;
/**
* Checks if the response included a warning and signals that warning to the
* WarningMessageCallback.
*
* @param response
* Response to process
*/
void processResponseWarnings(Response response, WarningMessageCallback warningCallback);
/**
* Writes directly to the {@code OutputStream} of the underlying connection.
*
* Use of this method might lead to hard to find race conditions in the protocol. It is currently only used
* to allow {@link org.firebirdsql.gds.ng.FbDatabase#cancelOperation(int)} to work.
*
*
* @param data
* Data to write
* @throws IOException
* If there is no socket, the socket is closed, or for errors writing to the socket.
* @see WireConnection#writeDirect(byte[])
*/
void writeDirect(byte[] data) throws IOException;
/**
* Receive authentication response from the server.
*
* This method is only relevant for protocol V13 or higher.
*
*
* @param acceptPacket
* Packet with {@code op_cond_accept} data, or {@code null} when the data should be read from the
* connection.
* @param dbCryptCallback
* Database encryption callback (ignored by protocols v12 and lower)
* @param processAttachCallback
* Callback for processing the final attach response
* @throws IOException
* For errors reading the response from the connection.
* @throws SQLException
* For errors returned from the server, or when attempting to
* read.
*/
void authReceiveResponse(FbWireAttachment.AcceptPacket acceptPacket,
DbCryptCallback dbCryptCallback,
ProcessAttachCallback processAttachCallback)
throws IOException, SQLException;
interface ProcessAttachCallback {
void processAttachResponse(GenericResponse response);
}
}