Open Source Repository

Home /hibernate/hibernate-3.2.7.ga | Repository Home


org/hibernate/jdbc/Batcher.java
//$Id: Batcher.java 10040 2006-06-22 19:51:43Z [email protected] $
package org.hibernate.jdbc;

import java.sql.CallableStatement;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

import org.hibernate.HibernateException;
import org.hibernate.ScrollMode;
import org.hibernate.dialect.Dialect;

/**
 * Manages <tt>PreparedStatement</tt>s for a session. Abstracts JDBC
 * batching to maintain the illusion that a single logical batch
 * exists for the whole session, even when batching is disabled.
 * Provides transparent <tt>PreparedStatement</tt> caching.
 *
 @see java.sql.PreparedStatement
 @see org.hibernate.impl.SessionImpl
 @author Gavin King
 */
public interface Batcher {
  /**
   * Get a prepared statement for use in loading / querying. If not explicitly
   * released by <tt>closeQueryStatement()</tt>, it will be released when the
   * session is closed or disconnected.
   */
  public PreparedStatement prepareQueryStatement(String sql, boolean scrollable, ScrollMode scrollModethrows SQLException, HibernateException;
  /**
   * Close a prepared statement opened with <tt>prepareQueryStatement()</tt>
   */
  public void closeQueryStatement(PreparedStatement ps, ResultSet rsthrows SQLException;
  /**
   * Get a prepared statement for use in loading / querying. If not explicitly
   * released by <tt>closeQueryStatement()</tt>, it will be released when the
   * session is closed or disconnected.
   */
  public CallableStatement prepareCallableQueryStatement(String sql, boolean scrollable, ScrollMode scrollModethrows SQLException, HibernateException;
  
  
  /**
   * Get a non-batchable prepared statement to use for selecting. Does not
   * result in execution of the current batch.
   */
  public PreparedStatement prepareSelectStatement(String sqlthrows SQLException, HibernateException;

  /**
   * Get a non-batchable prepared statement to use for inserting / deleting / updating,
   * using JDBC3 getGeneratedKeys ({@link Connection#prepareStatement(String, int)}).
   <p/>
   * Must be explicitly released by {@link #closeStatement} after use.
   */
  public PreparedStatement prepareStatement(String sql, boolean useGetGeneratedKeysthrows SQLException, HibernateException;

  /**
   * Get a non-batchable prepared statement to use for inserting / deleting / updating.
   * using JDBC3 getGeneratedKeys ({@link Connection#prepareStatement(String, String[])}).
   <p/>
   * Must be explicitly released by {@link #closeStatement} after use.
   */
  public PreparedStatement prepareStatement(String sql, String[] columnNamesthrows SQLException, HibernateException;

  /**
   * Get a non-batchable prepared statement to use for inserting / deleting / updating.
   <p/>
   * Must be explicitly released by {@link #closeStatement} after use.
   */
  public PreparedStatement prepareStatement(String sqlthrows SQLException, HibernateException;

  /**
   * Get a non-batchable callable statement to use for inserting / deleting / updating.
   <p/>
   * Must be explicitly released by {@link #closeStatement} after use.
   */
  public CallableStatement prepareCallableStatement(String sqlthrows SQLException, HibernateException;

  /**
   * Close a prepared or callable statement opened using <tt>prepareStatement()</tt> or <tt>prepareCallableStatement()</tt>
   */
  public void closeStatement(PreparedStatement psthrows SQLException;

  /**
   * Get a batchable prepared statement to use for inserting / deleting / updating
   * (might be called many times before a single call to <tt>executeBatch()</tt>).
   * After setting parameters, call <tt>addToBatch</tt> - do not execute the
   * statement explicitly.
   @see Batcher#addToBatch
   */
  public PreparedStatement prepareBatchStatement(String sqlthrows SQLException, HibernateException;

  /**
   * Get a batchable callable statement to use for inserting / deleting / updating
   * (might be called many times before a single call to <tt>executeBatch()</tt>).
   * After setting parameters, call <tt>addToBatch</tt> - do not execute the
   * statement explicitly.
   @see Batcher#addToBatch
   */
  public CallableStatement prepareBatchCallableStatement(String sqlthrows SQLException, HibernateException;

  /**
   * Add an insert / delete / update to the current batch (might be called multiple times
   * for single <tt>prepareBatchStatement()</tt>)
   */
  public void addToBatch(Expectation expectationthrows SQLException, HibernateException;

  /**
   * Execute the batch
   */
  public void executeBatch() throws HibernateException;

  /**
   * Close any query statements that were left lying around
   */
  public void closeStatements();
  /**
   * Execute the statement and return the result set
   */
  public ResultSet getResultSet(PreparedStatement psthrows SQLException;
  /**
   * Execute the statement and return the result set from a callable statement
   */
  public ResultSet getResultSet(CallableStatement ps, Dialect dialectthrows SQLException;

  /**
   * Must be called when an exception occurs
   @param sqle the (not null) exception that is the reason for aborting
   */
  public void abortBatch(SQLException sqle);

  /**
   * Cancel the current query statement
   */
  public void cancelLastQuery() throws HibernateException;

  public boolean hasOpenResources();

  public String openResourceStatsAsString();

  // TODO : remove these last two as batcher is no longer managing connections

  /**
   * Obtain a JDBC connection
   */
  public Connection openConnection() throws HibernateException;
  /**
   * Dispose of the JDBC connection
   */
  public void closeConnection(Connection connthrows HibernateException;
  
  /**
   * Set the transaction timeout to <tt>seconds</tt> later
   * than the current system time.
   */
  public void setTransactionTimeout(int seconds);
  /**
   * Unset the transaction timeout, called after the end of a 
   * transaction.
   */
  public void unsetTransactionTimeout();
}