/*
 * 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;

import java.sql.Connection;

Models the logical notion of a JDBC Connection.  We may release/re-acquire physical JDBC connections under the
covers, but this logically represents the overall access to the JDBC Connection.
Author:
Steve Ebersole/**
 * Models the logical notion of a JDBC Connection.  We may release/re-acquire physical JDBC connections under the
 * covers, but this logically represents the overall access to the JDBC Connection.
 *
 * @author Steve Ebersole
 */
public interface LogicalConnection {
	
Is this (logical) JDBC Connection still open/active. In other words, has close not been called yet? 
Returns:
true if still open (close has not been called yet); false if not open ((close has been called)./**
	 * Is this (logical) JDBC Connection still open/active.  In other words, has {@link #close} not been called yet?
	 *
	 * @return {@code true} if still open ({@link #close} has not been called yet); {@code false} if not open
	 * (({@link #close} has been called).
	 */
	boolean isOpen();

	
Closes the JdbcSession, making it inactive and forcing release of any held resources
Returns:
Legacy :(  Returns the JDBC Connection *if* the user passed in a Connection originally./**
	 * Closes the JdbcSession, making it inactive and forcing release of any held resources
	 *
	 * @return Legacy :(  Returns the JDBC Connection *if* the user passed in a Connection originally.
	 */
	Connection close();

	
Is this JdbcSession currently physically connected (meaning does it currently hold a JDBC Connection)?
Returns:
true if the JdbcSession currently hold a JDBC Connection; false if it does not./**
	 * Is this JdbcSession currently physically connected (meaning does it currently hold a JDBC Connection)?
	 *
	 * @return {@code true} if the JdbcSession currently hold a JDBC Connection; {@code false} if it does not.
	 */
	boolean isPhysicallyConnected();

	
Provides access to the registry of JDBC resources associated with this LogicalConnection.
Throws:
ResourceClosedException – if the LogicalConnection is closed
Returns:
The JDBC resource registry./**
	 * Provides access to the registry of JDBC resources associated with this LogicalConnection.
	 *
	 * @return The JDBC resource registry.
	 *
	 * @throws org.hibernate.ResourceClosedException if the LogicalConnection is closed
	 */
	ResourceRegistry getResourceRegistry();

}