Package org.intermine.sql.writebatch

Class 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.
    Author:
    Matthew Wakeling

    • Constructor Summary

      Constructors 
      Constructor Description
      Batch​(BatchWriter batchWriter)
      Constructs an empty Batch, with no tables.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.