org.hibernate.engine.jdbc.spi.JdbcCoordinator.java Source code

Introduction

Here is the source code for org.hibernate.engine.jdbc.spi.JdbcCoordinator.java

Source

/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
 */
package org.hibernate.engine.jdbc.spi;

import java.io.IOException;
import java.io.ObjectOutputStream;
import java.io.Serializable;
import java.sql.Connection;
import java.sql.Statement;

import org.hibernate.ConnectionReleaseMode;
import org.hibernate.engine.jdbc.batch.spi.Batch;
import org.hibernate.engine.jdbc.batch.spi.BatchKey;
import org.hibernate.jdbc.WorkExecutorVisitable;
import org.hibernate.resource.jdbc.ResourceRegistry;
import org.hibernate.resource.jdbc.spi.LogicalConnectionImplementor;
import org.hibernate.resource.jdbc.spi.PhysicalConnectionHandlingMode;
import org.hibernate.resource.transaction.backend.jdbc.spi.JdbcResourceTransactionAccess;
import org.hibernate.resource.transaction.spi.TransactionCoordinatorOwner;

/**
 * Coordinates JDBC-related activities.
 *
 * @author Steve Ebersole
 * @author Brett Meyer
 */
public interface JdbcCoordinator extends Serializable, TransactionCoordinatorOwner, JdbcResourceTransactionAccess {
    //   /**
    //    * Retrieve the transaction coordinator associated with this JDBC coordinator.
    //    *
    //    * @return The transaction coordinator
    //    */
    //   public TransactionCoordinator getTransactionCoordinator();

    /**
     * Retrieves the logical connection associated with this JDBC coordinator.
     *
     * @return The logical connection
     */
    LogicalConnectionImplementor getLogicalConnection();

    /**
     * Get a batch instance.
     *
     * @param key The unique batch key.
     *
     * @return The batch
     */
    Batch getBatch(BatchKey key);

    /**
     * Execute the currently managed batch (if any)
     */
    void executeBatch();

    /**
     * Abort the currently managed batch (if any)
     */
    void abortBatch();

    /**
     * Obtain the statement preparer associated with this JDBC coordinator.
     *
     * @return This coordinator's statement preparer
     */
    StatementPreparer getStatementPreparer();

    /**
     * Obtain the resultset extractor associated with this JDBC coordinator.
     *
     * @return This coordinator's resultset extractor
     */
    ResultSetReturn getResultSetReturn();

    /**
     * Callback to let us know that a flush is beginning.  We use this fact
     * to temporarily circumvent aggressive connection releasing until after
     * the flush cycle is complete {@link #flushEnding()}
     */
    void flushBeginning();

    /**
     * Callback to let us know that a flush is ending.  We use this fact to
     * stop circumventing aggressive releasing connections.
     */
    void flushEnding();

    /**
     * Close this coordinator and release and resources.
     *
     * @return The {@link Connection} associated with the managed {@link #getLogicalConnection() logical connection}
     *
     * @see org.hibernate.resource.jdbc.spi.LogicalConnectionImplementor#close
     */
    Connection close();

    /**
     * Signals the end of transaction.
     * <p/>
     * Intended for use from the transaction coordinator, after local transaction completion.  Used to conditionally
     * release the JDBC connection aggressively if the configured release mode indicates.
     */
    void afterTransaction();

    /**
     * Used to signify that a statement has completed execution which may
     * indicate that this logical connection need to perform an
     * aggressive release of its physical connection.
     */
    void afterStatementExecution();

    /**
     * Perform the requested work handling exceptions, coordinating and handling return processing.
     *
     * @param work The work to be performed.
     * @param <T> The result type.
     * @return The work result.
     */
    <T> T coordinateWork(WorkExecutorVisitable<T> work);

    /**
     * Attempt to cancel the last query sent to the JDBC driver.
     */
    void cancelLastQuery();

    /**
    * Calculate the amount of time, in seconds, still remaining before transaction timeout occurs.
    *
    * @return The number of seconds remaining until until a transaction timeout occurs.  A negative value indicates
    * no timeout was requested.
    *
    * @throws org.hibernate.TransactionException Indicates the time out period has already been exceeded.
    */
    int determineRemainingTransactionTimeOutPeriod();

    /**
     * Enable connection releases
     */
    void enableReleases();

    /**
     * Disable connection releases
     */
    void disableReleases();

    /**
     * Register a query statement as being able to be cancelled.
     * 
     * @param statement The cancel-able query statement.
     */
    void registerLastQuery(Statement statement);

    /**
     * Can this coordinator be serialized?
     *
     * @return {@code true} indicates the coordinator can be serialized.
     */
    boolean isReadyForSerialization();

    /**
     * The release mode under which this logical connection is operating.
     *
     * @return the release mode.
     *
     * @deprecated (since 5.2) use {@link PhysicalConnectionHandlingMode} via {@link #getLogicalConnection} instead
     */
    @Deprecated
    default ConnectionReleaseMode getConnectionReleaseMode() {
        return getLogicalConnection().getConnectionHandlingMode().getReleaseMode();
    }

    /**
     * The mode for physical handling of the JDBC Connection
     *
     * @return The JDBC Connection handlng mode
     *
     * @deprecated (since 5.2) access via {@link #getLogicalConnection} instead
     */
    @Deprecated
    default PhysicalConnectionHandlingMode getConnectionHandlingMode() {
        return getLogicalConnection().getConnectionHandlingMode();
    }

    /**
     * @deprecated (since 5.2) access via {@link #getLogicalConnection} instead
     */
    @Deprecated
    default ResourceRegistry getResourceRegistry() {
        return getLogicalConnection().getResourceRegistry();
    }

    void serialize(ObjectOutputStream objectOutputStream) throws IOException;

}