Author: steve.ebersole(a)jboss.com Date: 2007-09-21 12:21:18 -0400 (Fri, 21 Sep 2007) New Revision: 14017 Modified: sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/AbstractBatchImpl.java sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/Batch.java sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchBuilder.java sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchObserver.java sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchingBatch.java sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/NonBatchingBatch.java Log: javadoc of batch stuff Modified: sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/AbstractBatchImpl.java =================================================================== --- sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/AbstractBatchImpl.java 2007-09-20 21:59:46 UTC (rev 14016) +++ sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/AbstractBatchImpl.java 2007-09-21 16:21:18 UTC (rev 14017) @@ -31,7 +31,7 @@ import org.hibernate.jdbc.proxy.ProxyBuilder; /** - * AbstractBatchImpl implementation + * Convenience base class for implementors of the Batch interface. * * @author Steve Ebersole */ @@ -50,20 +50,49 @@ this.connectionProxy = ProxyBuilder.buildConnection( logicalConnection ); } + /** + * Perform batch execution. + * <p/> + * This is called from the explicit {@link #execute() execution}, but may also be called from elsewhere + * depending on the exact implementation. + */ protected abstract void doExecuteBatch(); + /** + * Convenience access to the underlying JDbC services. + * + * @return The underlying JDBC services. + */ protected JDBCServices getJdbcServices() { return logicalConnection.getJdbcServices(); } + /** + * Access to the batch's map of statements (keyed by SQL statement string). + * + * @return This batch's statements. + */ protected LinkedHashMap getStatements() { return statements; } + /** + * {@inheritDoc} + */ public final Object getKey() { return key; } + /** + * {@inheritDoc} + */ + public void addObserver(BatchObserver observer) { + observers.add( observer ); + } + + /** + * {@inheritDoc} + */ public final PreparedStatement getBatchStatement(String sql, boolean callable) { PreparedStatement statement = ( PreparedStatement ) statements.get( sql ); if ( statement == null ) { @@ -92,6 +121,9 @@ } } + /** + * {@inheritDoc} + */ public final void execute() { notifyObserversExplicitExecution(); if ( statements.isEmpty() ) { @@ -123,12 +155,9 @@ log.error( "sqlexception escaped proxy", e ); } } + getStatements().clear(); } - public void addObserver(BatchObserver observer) { - observers.add( observer ); - } - private void notifyObserversExplicitExecution() { Iterator itr = observers.iterator(); while ( itr.hasNext() ) { @@ -136,10 +165,21 @@ } } + /** + * Convenience method to notify registered observers of an implicit execution of this batch. + */ protected void notifyObserversImplicitExecution() { Iterator itr = observers.iterator(); while ( itr.hasNext() ) { ( ( BatchObserver ) itr.next() ).batchImplicitlyExecuted(); } } + + public void release() { + if ( getStatements() != null && !getStatements().isEmpty() ) { + log.info( "On release of batch it still contained JDBC statements" ); + } + releaseStatements(); + observers.clear(); + } } Modified: sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/Batch.java =================================================================== --- sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/Batch.java 2007-09-20 21:59:46 UTC (rev 14016) +++ sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/Batch.java 2007-09-21 16:21:18 UTC (rev 14017) @@ -20,15 +20,53 @@ import org.hibernate.jdbc.Expectation; /** - * Conceptually models a batch, but unlike directly in JDBC, here we add the ability to - * batch together multiple statements at a time. + * Conceptually models a batch. + * <p/> + * Unlike directly in JDBC, here we add the ability to batch together multiple statements at a time. In the underlying + * JDBC this correlates to multiple {@link PreparedStatement} objects (one for each DML string) maintained within the + * batch. * * @author Steve Ebersole */ public interface Batch { + /** + * Retrieves the object being used to key (uniquely identify) this batch. + * + * @return The batch key. + */ public Object getKey(); + + /** + * Adds an observer to this batch. + * + * @param observer The batch observer. + */ public void addObserver(BatchObserver observer); + + /** + * Get a statement which is part of the batch, creating if necessary (and storing for next time). + * + * @param sql The SQL statement. + * @param callable Is the SQL statement callable? + * @return The prepared statement instance, representing the SQL statement. + */ public PreparedStatement getBatchStatement(String sql, boolean callable); + + /** + * Indicates completion of the current part of the batch. + * + * @param expectation The expectation for the part's result. + */ public void addToBatch(Expectation expectation); + + /** + * Execute this batch. + */ public void execute(); + + /** + * Used to indicate that the batch instance is no longer needed and that, therefore, it can release its + * resources. + */ + public void release(); } Modified: sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchBuilder.java =================================================================== --- sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchBuilder.java 2007-09-20 21:59:46 UTC (rev 14016) +++ sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchBuilder.java 2007-09-21 16:21:18 UTC (rev 14017) @@ -21,14 +21,14 @@ import org.hibernate.jdbc.impl.LogicalConnectionImplementor; /** - * BatchBuilder implementation + * A builder for {@link Batch} instances. * * @author Steve Ebersole */ public class BatchBuilder { private static final Logger log = LoggerFactory.getLogger( BatchBuilder.class ); - // todo : eventually have this take the Settings; this form is needed for testing because Settings is currently final :( + // todo : eventually have this take the Settings; this form is needed for testing because Settings is currently final and does not expose the batch size :( private int size; Modified: sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchObserver.java =================================================================== --- sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchObserver.java 2007-09-20 21:59:46 UTC (rev 14016) +++ sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchObserver.java 2007-09-21 16:21:18 UTC (rev 14017) @@ -16,11 +16,18 @@ package org.hibernate.jdbc.batch; /** - * BatchObserver contract + * An observer contract for batch events. * * @author Steve Ebersole */ public interface BatchObserver { + /** + * Indicates explicit execution of the batch via a call to {@link Batch#execute()}. + */ public void batchExplicitlyExecuted(); + + /** + * Indicates an implicit execution of the batch. + */ public void batchImplicitlyExecuted(); } Modified: sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchingBatch.java =================================================================== --- sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchingBatch.java 2007-09-20 21:59:46 UTC (rev 14016) +++ sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/BatchingBatch.java 2007-09-21 16:21:18 UTC (rev 14017) @@ -28,7 +28,8 @@ import org.hibernate.HibernateException; /** - * BatchingBatch implementation + * A {@link Batch} implementation which does batching based on a given size. Once the batch size is exceeded, the + * batch is implicitly executed. * * @author Steve Ebersole */ @@ -45,6 +46,9 @@ this.expectations = new Expectation[ batchSize ]; } + /** + * {@inheritDoc} + */ public void addToBatch(Expectation expectation) { if ( !expectation.canBeBatched() ) { throw new HibernateException( "attempting to batch an operation which cannot be batched" ); @@ -69,6 +73,9 @@ } } + /** + * {@inheritDoc} + */ protected void doExecuteBatch() { if ( batchPosition == 0 ) { log.debug( "no batched statements to execute" ); Modified: sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/NonBatchingBatch.java =================================================================== --- sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/NonBatchingBatch.java 2007-09-20 21:59:46 UTC (rev 14016) +++ sandbox/trunk/jdbc-proxy/src/main/java/org/hibernate/jdbc/batch/NonBatchingBatch.java 2007-09-21 16:21:18 UTC (rev 14017) @@ -27,7 +27,8 @@ import org.hibernate.jdbc.impl.LogicalConnectionImplementor; /** - * NonBatchingBatch implementation + * An implementation of {@link Batch} which does not perform batching. It simply executes each statement as it is + * encountered. * * @author Steve Ebersole */