Package net.sf.basedb.core

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:

• It can only work with items that are already in the database. It is not possible to use the batcher with items that are created in the same transaction.
• It can only work with items of a single Item type.
• A item can only be processed once (eg. setCurrentItem(Annotatable) can only be called once for a given item.
• Annotatable.getAnnotationSet() must not have been called on the item before using it with this batcher.
• The annotation types to work with must be specified before the first call to setCurrentItem(Annotatable). It is not possible to work with other annotations.
• The batcher only works with Annotation.Source.PRIMARY annotations.
• The setValues(AnnotationType, List, Unit, boolean) can only be called once per item and annotation type.

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	AnnotationBatcher.Change	A flag indicating what type of change that was made to an annotation as a result of calling setValues(AnnotationType, List, Unit, boolean)
static class	AnnotationBatcher.CurrentAnnotationInfo	Holds information about an annotation for the current item.
(package private) static class	AnnotationBatcher.InsertBatcher	Batcher implementation for inserting into tables.
(package private) static class	AnnotationBatcher.UpdateBatcher	Batcher implementation for updating and deleting from tables.

Field Summary

Fields

Modifier and Type	Field	Description
private final int	activeProjectId
private final List<AnnotationBatcher.InsertBatcher>	allInsertBatchers
private final List<AnnotationBatcher.UpdateBatcher>	allUpdateBatchers
private final Date	batchDate
private int	currentAnnotationSetId
private Map<Integer,AnnotationBatcher.CurrentAnnotationInfo>	currentInfo
private Annotatable	currentItem
private final AnnotationBatcher.UpdateBatcher	deleteFromAnnotations
private final AnnotationBatcher.UpdateBatcher	deleteFromParameterValues
private final AnnotationBatcher.UpdateBatcher	deleteInheritedAnnotations
private boolean	deleteSnapshotIfModifed
private final AnnotationBatcher.UpdateBatcher[]	deleteValues
private final Dialect	dialect
private final int[]	discriminators
private boolean	evictFromSecondLevelCacheIfModified
private final AnnotationBatcher.InsertBatcher	insertIntoAnnotations
private final AnnotationBatcher.InsertBatcher	insertIntoAnnotationSets
private final AnnotationBatcher.InsertBatcher	insertIntoParameterValues
private final AnnotationBatcher.UpdateBatcher[]	insertValues
private final boolean	isDebugEnabled
private final Item	itemType
private final Query<Object[]>	loadAnnotationInfo
private final Query<Object[]>[]	loadAnnotationValues
private static final Logger	log
private final LoggingInterceptor	loggingInterceptor
private final AnnotationBatcher.UpdateBatcher	nullifyClonedReferences
private int	numItems
private final Integer	projectId
private final Cache	secondLevelCache
private final List<Integer>	snapshotsToDelete
private final StatelessSession	statelessSession
private final Map<String,UnitConverter>	unitConvertes
private final AnnotationBatcher.UpdateBatcher	updateAnnotations
private final AnnotationBatcher.UpdateBatcher	updateItemTable
private final AnnotationBatcher.UpdateBatcher	updateOverrideId
private final List<Integer>[]	valueIds

Fields inherited from class net.sf.basedb.core.AbstractBatcher

debugSqlEnabled, logSql

Constructor Summary

Constructors

Modifier	Constructor	Description
	AnnotationBatcher(DbControl dc, Item itemType)	Create a new batcher instance.
private	AnnotationBatcher(DbControl dc, Item itemType, Integer projectId)	Create a new batcher instance.
	AnnotationBatcher(DbControl dc, Item itemType, Project project)	Create a new batcher instance.

Method Summary

Modifier and Type	Method	Description
void	addAnnotationTypes(Collection<AnnotationType> types)	Add annotation types to work with.
private AnnotationBatcher.InsertBatcher	createInsertBatcher(Connection c, String sql, int... types)
private AnnotationBatcher.UpdateBatcher	createUpdateBatcher(Connection c, String sql, int... types)
void	flush()	Flush the batchers.
private UnitConverter	getUnitConverter(Unit from, Unit to)	Get/create a unit converter for converting between two units.
protected void	onBeforeClose()	Let a subclass cleanup itself before the connection to the database is closed.
void	setCurrentItem(Annotatable item)	Set the current item to work with from now on.
AnnotationBatcher.Change	setValue(AnnotationType annotationType, Object value, Unit unit, boolean merge)	Add, update or delete a single-valued annotation.
AnnotationBatcher.Change	setValues(AnnotationType annotationType, List<?> values, Unit unit, boolean merge)	Add, update or delete annotation values for the current item.

Methods inherited from class net.sf.basedb.core.AbstractBatcher

analyzeTable, close, getBatchSize, getDbControl, getSessionControl, isClosed, setBatchSize, setDbControl, updateLastAccess

Methods inherited from class java.lang.Object

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

Field Details

log

private static final Logger log

isDebugEnabled

private final boolean isDebugEnabled

itemType

private final Item itemType

activeProjectId

private final int activeProjectId

projectId

private final Integer projectId

batchDate

private final Date batchDate

statelessSession

private final StatelessSession statelessSession

dialect

private final Dialect dialect

secondLevelCache

private final Cache secondLevelCache

loggingInterceptor

private final LoggingInterceptor loggingInterceptor

discriminators

private final int[] discriminators

loadAnnotationInfo

private final Query<Object[]> loadAnnotationInfo

loadAnnotationValues

private final Query<Object[]>[] loadAnnotationValues

insertIntoParameterValues

private final AnnotationBatcher.InsertBatcher insertIntoParameterValues

insertIntoAnnotations

private final AnnotationBatcher.InsertBatcher insertIntoAnnotations

updateAnnotations

private final AnnotationBatcher.UpdateBatcher updateAnnotations

updateOverrideId

private final AnnotationBatcher.UpdateBatcher updateOverrideId

insertIntoAnnotationSets

private final AnnotationBatcher.InsertBatcher insertIntoAnnotationSets

updateItemTable

private final AnnotationBatcher.UpdateBatcher updateItemTable

allUpdateBatchers

private final List<AnnotationBatcher.UpdateBatcher> allUpdateBatchers

allInsertBatchers

private final List<AnnotationBatcher.InsertBatcher> allInsertBatchers

deleteFromAnnotations

private final AnnotationBatcher.UpdateBatcher deleteFromAnnotations

deleteFromParameterValues

private final AnnotationBatcher.UpdateBatcher deleteFromParameterValues

nullifyClonedReferences

private final AnnotationBatcher.UpdateBatcher nullifyClonedReferences

deleteInheritedAnnotations

private final AnnotationBatcher.UpdateBatcher deleteInheritedAnnotations

deleteValues

private final AnnotationBatcher.UpdateBatcher[] deleteValues

insertValues

private final AnnotationBatcher.UpdateBatcher[] insertValues

numItems

private int numItems

currentItem

private Annotatable currentItem

currentAnnotationSetId

private int currentAnnotationSetId

deleteSnapshotIfModifed

private boolean deleteSnapshotIfModifed

evictFromSecondLevelCacheIfModified

private boolean evictFromSecondLevelCacheIfModified

valueIds

private final List<Integer>[] valueIds

currentInfo

private Map<Integer,AnnotationBatcher.CurrentAnnotationInfo> currentInfo

snapshotsToDelete

private final List<Integer> snapshotsToDelete

unitConvertes

private final Map<String,UnitConverter> unitConvertes

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:

• Batcher.close()

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