Class AnnotationBatcher

java.lang.Object
net.sf.basedb.core.AbstractBatcher
net.sf.basedb.core.AnnotationBatcher
All Implemented Interfaces:
AutoCloseable, Batcher

public class AnnotationBatcher extends AbstractBatcher
Batcher implementation for adding, updating and removing multiple annotations to a large number of items in a single transaction while keeping the memory usage as low as possible. The batcher bypasses Hibernate where it is possible and uses direct SQL to access the database. There are some limitations: The batcher support project-specific annotations. The default mode (setting projectId=null) makes the batcher to use the currently active project. Project-specific annotation values will only be created if they are different from the default values. Setting projectId to 0 or to a specific project makes the batcher to only consider default or the project-specific values. The currently active project is not taken into account.
Since:
3.8
Author:
nicklas
  • Field Details

  • Constructor Details

    • AnnotationBatcher

      public AnnotationBatcher(DbControl dc, Item itemType)
      Create a new batcher instance. Using this constructor creates a batcher that, for project-specific annotation types, automatically handles either the default or project-specific value depending on the currently active project and wheter a value already exists or not.
      Parameters:
      dc - A DbControl to use for database access
      itemType - The type of items to work with. This must be an annotatable item type.
    • AnnotationBatcher

      public AnnotationBatcher(DbControl dc, Item itemType, Project project)
      Create a new batcher instance. Using this constructor creates a batcher that, for project-specific annotation types, always work with the values for the given project (or the default values if project=null). The currently active project is ignored.
      Parameters:
      dc - A DbControl to use for database access
      itemType - The type of items to work with. This must be an annotatable item type.
      project - Specify a project to only consider values for that project when working with a project-specific annotation, or null to only consider default values
      Since:
      3.11
    • AnnotationBatcher

      private AnnotationBatcher(DbControl dc, Item itemType, Integer projectId)
      Create a new batcher instance.
      Parameters:
      dc - A DbControl to use for database access
      itemType - The type of items to work with. This must be an annotatable item type.
      projectId - Specify a project id to only consider values for that project when working with a project-specific annotation, or 0 to only consider default values, or null to automatically use the default or project-specific values for the currently active project
      Since:
      3.11
  • Method Details

    • flush

      public void flush()
      Flush the batchers.
      See Also:
    • onBeforeClose

      protected void onBeforeClose()
      Description copied from class: AbstractBatcher
      Let a subclass cleanup itself before the connection to the database is closed. This method is called by the AbstractBatcher.close() method after Batcher.flush() has been called but before the connection to the database is lost. Typical use of this method is to update properties on parent object (for example, spot count) and to close open SQL statements.
      Overrides:
      onBeforeClose in class AbstractBatcher
    • createInsertBatcher

      private AnnotationBatcher.InsertBatcher createInsertBatcher(Connection c, String sql, int... types) throws SQLException
      Throws:
      SQLException
    • createUpdateBatcher

      private AnnotationBatcher.UpdateBatcher createUpdateBatcher(Connection c, String sql, int... types) throws SQLException
      Throws:
      SQLException
    • getUnitConverter

      private UnitConverter getUnitConverter(Unit from, Unit to)
      Get/create a unit converter for converting between two units.
    • addAnnotationTypes

      public void addAnnotationTypes(Collection<AnnotationType> types)
      Add annotation types to work with. It is possible to call this method multiple times, but it must be done before setCurrentItem(Annotatable) is called. The annotation types must be enabled for use with the item type this batcher is working with and the current user must have USE permission for all annotation types.
    • setCurrentItem

      public void setCurrentItem(Annotatable item)
      Set the current item to work with from now on. Before calling this method the addAnnotationTypes(Collection) must have specified the annotation types to work with. The item must not have been used with this method before and the Annotatable.getAnnotationSet() method must not have been called on the item. If the item can be used, the batcher will immediately load all existing annotations and their values and prepare for adding, updating or removing values.
    • setValue

      public AnnotationBatcher.Change setValue(AnnotationType annotationType, Object value, Unit unit, boolean merge)
      Add, update or delete a single-valued annotation. See setValues(AnnotationType, List, Unit, boolean) for more information.
    • setValues

      public AnnotationBatcher.Change setValues(AnnotationType annotationType, List<?> values, Unit unit, boolean merge)
      Add, update or delete annotation values for the current item. If the current item doesn't have any values for the annotation type the outcome is one of the following:
      • ADDED: if there is at least one value in the list
      • NO_CHANGE: if the list of values is null or empty
      If the current item already have values for the annotation type the outcome is one of the following:
      • UPDATED: if the values are different from the current
      • DELETED: if the list of values is null or empty
      • NO_CHANGE: if the values are the same as the existing values
      The given list of values are of course always validated against the specification in the annotations (eg. correct value type, allowed by the enumeration, within bounds of min and max values, etc.)
      Parameters:
      annotationType - The annotation type, which must be one of the annotation types specified when creating the batcher
      values - The values to set or null/empty to remove values
      unit - The unit of the values. Ignored if the annotation type doesn't use units.
      merge - If TRUE and the annotation type allows an unlimted number of annotations (multiplicity=0) merges the new values with the existing values. Ignored if multiplicity > 0.
      Returns:
      The resulting change