org.intermine.sql.writebatch
Class Batch

java.lang.Object
  org.intermine.sql.writebatch.Batch

public class Batch
extends java.lang.Object

A class representing a collection of writes to an SQL database. This class is intended for the purpose of improving the performance of systems that write to an SQL database, by bunching all the writes into a large batch, and then using tricks to speed up the batch commit. One should create one of these objects with a BatchWriter, which will perform the writes. BatchWriters are database-specific, in that they use different tricks to speed up the write, some of which depend on a certain database product.

Constructor Summary

Batch(BatchWriter batchWriter)
Constructs an empty Batch, with no tables.

Method Summary

void	addRow(java.sql.Connection con, java.lang.String name, java.lang.Object idValue, java.lang.String[] colNames, java.lang.Object[] values) Adds a row to the batch for a given table.
void	addRow(java.sql.Connection con, java.lang.String name, java.lang.String leftColName, java.lang.String rightColName, int left, int right) Adds a row to the batch for a given indirection table.
void	backgroundFlush(java.sql.Connection con, java.util.Set<java.lang.String> filter) Flushes the batch out to the database server, but does not guarantee that the operation is finished when this method returns.
void	backgroundFlush(java.sql.Connection con, java.util.Set<java.lang.String> filter, boolean needBatchCommit) Flushes the batch out to the database server, but does not guarantee that the operation is finished when this method returns.
void	batchCommit(java.sql.Connection con) Flushes the batch out to the database server, then commits and re-opens the transaction, but does not guarantee that the operation is finished when this method returns.
void	clear() Clears the batch without writing it to the database.
void	clearProblem() Clears the problem with the Batch.
void	close(java.sql.Connection con) Closes this BatchWriter.
void	deleteRow(java.sql.Connection con, java.lang.String name, java.lang.String idField, java.lang.Object idValue) Deletes a row from the batch for a given table.
void	deleteRow(java.sql.Connection con, java.lang.String name, java.lang.String leftColName, java.lang.String rightColName, int left, int right) Deletes a row from the batch for a given indirection table.
void	flush(java.sql.Connection con) Flushes the batch out to the database server.
void	flush(java.sql.Connection con, java.util.Set<java.lang.String> filter) Flushes the batch out to the database server.
void	setBatchWriter(BatchWriter batchWriter) Changes the BatchWriter for a new one.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Batch

public Batch(BatchWriter batchWriter)

Constructs an empty Batch, with no tables.

Parameters:

batchWriter - the BatchWriter to use

Method Detail

addRow

public void addRow(java.sql.Connection con,
                   java.lang.String name,
                   java.lang.Object idValue,
                   java.lang.String[] colNames,
                   java.lang.Object[] values)
            throws java.sql.SQLException

Adds a row to the batch for a given table. This action will override any previously deleted rows. Multiple rows with the same id can be added. If the table is not set up, then it will be set up using the provided array of field names, but without an idField (which will be set up the first time deleteRow is called).
Note that the batch may hang on to (and use) the Connection that you provide. It is your responsibility to call flush(Connection) before using that same Connection with anything other than this batch.

Parameters:

con - a Connection for writing to the database

name - the name of the table

idValue - the value of the id field for this row

colNames - an array of names of fields that are in the table

values - an array of Objects to be put in the row, in the same order as colNames

Throws:

java.sql.SQLException - if a flush occurs, and an error occurs while flushing

addRow

public void addRow(java.sql.Connection con,
                   java.lang.String name,
                   java.lang.String leftColName,
                   java.lang.String rightColName,
                   int left,
                   int right)
            throws java.sql.SQLException

Adds a row to the batch for a given indirection table.

Parameters:

con - a Connection for writing to the database

name - the name of the indirection table

leftColName - the name of the left-hand field

rightColName - the name of the right-hand field

left - the int value of the left field

right - the int value of the right field

Throws:

java.sql.SQLException - if a flush occurs, and an error occurs while flushing

deleteRow

public void deleteRow(java.sql.Connection con,
                      java.lang.String name,
                      java.lang.String idField,
                      java.lang.Object idValue)
               throws java.sql.SQLException

Deletes a row from the batch for a given table. This action will override any previously added rows. If the batch already shows that row to be in a deleted state (by idField), then no further action is taken. If the table if not set up, then it will be set up with an idField, but without an array of field names (which will be set up the first time addRow is called.
Note that the batch may hang on to (and use) the Connection that you provide. It is your responsibility to call flush(Connection) before using that same Connection with anything other than this batch.

Parameters:

con - a Connection for writing to the database

name - the name of the table

idField - the name of the field that you wish to use as a unique primary key

idValue - the value of the id field for the row to be deleted

Throws:

java.sql.SQLException - if a flush occurs, and an error occurs while flushing

deleteRow

public void deleteRow(java.sql.Connection con,
                      java.lang.String name,
                      java.lang.String leftColName,
                      java.lang.String rightColName,
                      int left,
                      int right)
               throws java.sql.SQLException

Deletes a row from the batch for a given indirection table.

Parameters:

con - a Connection for writing to the database

name - the name of the indirection table

leftColName - the name of the left-hand field

rightColName - the name of the right-hand field

left - the int value of the left field

right - the int value of the right field

Throws:

java.sql.SQLException - if a flush occurs, and an error occurs while flushing

flush

public void flush(java.sql.Connection con)
           throws java.sql.SQLException

Flushes the batch out to the database server. This method guarantees that the Connection is no longer in use by the batch even if it does not return normally.

Parameters:

con - a Connection for writing to the database

Throws:

java.sql.SQLException - if an error occurs while flushing

flush

public void flush(java.sql.Connection con,
                  java.util.Set<java.lang.String> filter)
           throws java.sql.SQLException

Flushes the batch out to the database server. This method guarantees that the Connection is no longer in use by the batch even if it does not return normally.

Parameters:

con - a Connection for writing to the database

filter - a Set of table names to write, or null to write all of them

Throws:

java.sql.SQLException - if an error occurs while flushing

batchCommit

public void batchCommit(java.sql.Connection con)
                 throws java.sql.SQLException

Flushes the batch out to the database server, then commits and re-opens the transaction, but does not guarantee that the operation is finished when this method returns. Do not use the Connection until you have called flush() or clear(). This method also guarantees that any operations being completed by this flush will be thrown out of this method. The entire Batch will be flushed - that is necessary to avoid leaving the database in an inconsistent state.

Parameters:

con - a Connection for writing to the database

Throws:

java.sql.SQLException - if an error occurs while flushing

backgroundFlush

public void backgroundFlush(java.sql.Connection con,
                            java.util.Set<java.lang.String> filter)
                     throws java.sql.SQLException

Flushes the batch out to the database server, but does not guarantee that the operation is finished when this method returns. Do not use the Connection until you have called flush() or clear(). This method also guarantees that any exception thrown by any operations being completed by this flush will be thrown out of this method.

Parameters:

con - a Connection for writing to the database

filter - a Set of the table names to write, or null to write all of them

Throws:

java.sql.SQLException - if an error occurs while flushing

backgroundFlush

public void backgroundFlush(java.sql.Connection con,
                            java.util.Set<java.lang.String> filter,
                            boolean needBatchCommit)
                     throws java.sql.SQLException

Flushes the batch out to the database server, but does not guarantee that the operation is finished when this method returns. Do not use the Connection until you have called flush() or clear(). This method also guarantees that any exception thrown by any operations being completed by this flush will be thrown out of this method.

Parameters:

con - a Connection for writing to the database

filter - a Set of the table names to write, or null to write all of them

needBatchCommit - true to add a FlushJobBatchCommit at the end

Throws:

java.sql.SQLException - if an error occurs while flushing

close

public void close(java.sql.Connection con)
           throws java.sql.SQLException

Closes this BatchWriter. This method guarantees that the Connection is no longer in use by the batch, and the background writer Thread will die soon, even if it does not return normally.

Parameters:

con - a Connection for writing to the database

Throws:

java.sql.SQLException - if an error occurs while flushing.

clear

public void clear()

Clears the batch without writing it to the database. NOTE that some data may have already made it to the database. It is expected that this will be called just before a transaction is aborted, removing the data anyway. This method guarantees that the Connection is no longer in use by the batch once it returns. This method also discards any deferred exceptions waiting to be thrown

setBatchWriter

public void setBatchWriter(BatchWriter batchWriter)

Changes the BatchWriter for a new one.

Parameters:

batchWriter - the new BatchWriter

clearProblem

public void clearProblem()

Clears the problem with the Batch.