/*
 * 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.resource.jdbc.spi;

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

import org.hibernate.resource.jdbc.LogicalConnection;

SPI contract for LogicalConnection
Author:
Steve Ebersole/**
 * SPI contract for LogicalConnection
 *
 * @author Steve Ebersole
 */
public interface LogicalConnectionImplementor extends LogicalConnection {
	
Exposes access to the "real" Connection.
@todo
: expose Connection as here?  or accept(WorkInConnection) where WorkInConnection is given access to Connection?
Returns:
The connection/**
	 * Exposes access to the "real" Connection.
	 *
	 * @todo : expose Connection as here?  or accept(WorkInConnection) where WorkInConnection is given access to Connection?
	 *
	 * @return The connection
	 */
	Connection getPhysicalConnection();

	PhysicalConnectionHandlingMode getConnectionHandlingMode();

	
Notification indicating a JDBC statement has been executed to trigger ConnectionReleaseMode.AFTER_STATEMENT releasing if needed /**
	 * Notification indicating a JDBC statement has been executed to trigger
	 * {@link org.hibernate.ConnectionReleaseMode#AFTER_STATEMENT} releasing if needed
	 */
	void afterStatement();

	
Notification indicating a transaction has completed to trigger ConnectionReleaseMode.AFTER_TRANSACTION releasing if needed /**
	 * Notification indicating a transaction has completed to trigger
	 * {@link org.hibernate.ConnectionReleaseMode#AFTER_TRANSACTION} releasing if needed
	 */
	void afterTransaction();

	
Manually disconnect the underlying JDBC Connection.  The assumption here
is that the manager will be reconnected at a later point in time.
Returns:
The connection maintained here at time of disconnect. null if there was no connection cached internally./**
	 * Manually disconnect the underlying JDBC Connection.  The assumption here
	 * is that the manager will be reconnected at a later point in time.
	 *
	 * @return The connection maintained here at time of disconnect.  {@code null} if
	 * there was no connection cached internally.
	 */
	Connection manualDisconnect();

	
Manually reconnect the underlying JDBC Connection.  Should be called at some point after manualDisconnect().
Params:
suppliedConnection – For user supplied connection strategy the user needs to hand us the connection
with which to reconnect.  It is an error to pass a connection in the other strategies./**
	 * Manually reconnect the underlying JDBC Connection.  Should be called at some point after manualDisconnect().
	 *
	 * @param suppliedConnection For user supplied connection strategy the user needs to hand us the connection
	 * with which to reconnect.  It is an error to pass a connection in the other strategies.
	 */
	void manualReconnect(Connection suppliedConnection);

	
Creates a shareable copy of itself for use in "shared sessions"
Returns:
The shareable copy.
Deprecated:
This method is not used by Hibernate./**
	 * Creates a shareable copy of itself for use in "shared sessions"
	 *
	 * @return The shareable copy.
	 *
	 * @deprecated This method is not used by Hibernate.
	 */
	@Deprecated
	LogicalConnectionImplementor makeShareableCopy();

	PhysicalJdbcTransaction getPhysicalJdbcTransaction();

	
Serialization hook
Params:
oos – The stream to write out state to
Throws:
IOException – Problem accessing stream/**
	 * Serialization hook
	 *
	 * @param oos The stream to write out state to
	 *
	 * @throws java.io.IOException Problem accessing stream
	 */
	void serialize(ObjectOutputStream oos) throws IOException;
}