//====================================================================
// ConnectionUsage.java
//====================================================================

package com.evident.database;

import java.sql.*;

/**
* Defines the basic means for using a managed database connection.
*/
public class ConnectionUsage {

	/** Indicates that auto commit should be disabled during usage. */
	public static final boolean WITHOUT_AUTO_COMMIT = true;

	/** Indicates whether commits are explicit. */
	protected boolean commitExplicitly;

	/** Indicates whether commits were originally automatic. */
	protected boolean originalCommitment;

	/**
	* Constructs a new ConnectionUsage.
	*/
	public ConnectionUsage( ) {
		this( !WITHOUT_AUTO_COMMIT );
	}

	/**
	* Constructs a new ConnectionUsage.
	* @param commitsExplicitly indicates whether commits are explicit.
	*/
	public ConnectionUsage( boolean commitsExplicitly ) {
		commitExplicitly = commitsExplicitly;
	}

	/**
	* Indicates whether the connection usage commits explicitly.
	*/
	public boolean commitsExplicitly( ) {
		return commitExplicitly;
	}

	/**
	* Prepares a database (connection) for usage.
	* @param connection a database connection.
	*/
	public void prepare( Connection connection ) {
		if (connection == null) return;
		if (commitExplicitly) {
			try {
				// save the original commitment setting
				originalCommitment = connection.getAutoCommit();
				// make commitments explicit
				connection.setAutoCommit( false );
			} catch( SQLException e ) {
				// the connection does not support changes to
				// its commitment, so ...
				commitExplicitly = false;
			}
		}
	}

	/**
	* Uses a database (connection) for some database operation(s). Derived
	* classes are expected to override this default implementation.
	* @param connection a database connection.
	* @return the result(s) from the database operation(s), the type of 
	* which is determined by the client.
	* @exception java.sql.SQLException if the implementor throws an
	* exception during a database operation.
	*/
	public Object use( Connection connection ) throws SQLException {
		return null;
	}

	/**
	* Rolls back any uncommitted changes made to a database (connection),
	* especially if the usage commits changes explicitly rather than 
	* automatically.
	* @param connection a database connection.
	*/
	public void rollback( Connection connection ) {
		if (connection == null) return;
		try {
			// roll back any uncommitted changes
			if (!connection.getAutoCommit()) {
				connection.rollback();
			}
		} catch( SQLException e ) {
			// ignore these exceptions if the connection does
			// not support commitment or rollback operations
		}
	}

	/**
	* Releases the supplied database (connection) after restoring its
	* original commitment setting.
	* @param connection a database connection.
	*/
	public void release( Connection connection ) {
		if (connection == null) return;
		try {
			// restore the original commitment if needed
			if (commitExplicitly) {
				connection.setAutoCommit( originalCommitment );
			}
			// release the connection if needed
			if (!connection.isClosed()) {
				connection.close();
			}
		} catch( SQLException e ) {
			// ignore these exceptions if the connection does
			// not support commitment or closure operations
		}
	}
}