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-jdk18 Show documentation
JDBC Driver for the Firebird RDBMS
There is a newer version: 4.0.10.java8
/*
 * 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);
    }
}