11:21 a.m.
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
*/