Package net.sf.basedb.plugins.batchimport

Class AbstractItemImporter<I extends BasicItem>

java.lang.Object
net.sf.basedb.core.plugin.AbstractPlugin
net.sf.basedb.plugins.AbstractFlatFileImporter
net.sf.basedb.plugins.batchimport.AbstractItemImporter<I>
All Implemented Interfaces:
AutoDetectingImporter, InteractivePlugin, Plugin, SignalTarget, ConfigureByExample
Direct Known Subclasses:
AnnotationTypeImporter, ArrayBatchImporter, ArrayDesignImporter, ArraySlideImporter, BioPlateImporter, BioSourceImporter, DerivedBioAssayImporter, ExtractImporter, FileImporter, KitImporter, PhysicalBioAssayImporter, RawBioAssayImporter, SampleImporter, TagImporter
public abstract class AbstractItemImporter<I extends BasicItem> extends AbstractFlatFileImporter implements InteractivePlugin, ConfigureByExample
An abstract base class for plug-ins that import items in batch. This class implements job configuration, file parsing, logging, error handling, etc. Actual implementations have to provide item-specific parts, such as:
Version:
2.8
Author:
nicklas
Last modified
$Date: 2023-11-09 09:16:57 +0100 (Thu, 09 Nov 2023) $

  • Field Details

    • CONFIGURE_OPTIONS

      private static final String CONFIGURE_OPTIONS
      See Also:

    • optionalColumnMapping

      protected static final StringParameterType optionalColumnMapping

    • requiredColumnMapping

      protected static final StringParameterType requiredColumnMapping

    • defaultsSection

      protected static final PluginParameter<String> defaultsSection

    • identificationSection

      protected static final PluginParameter<String> identificationSection

    • internalIdColumnMapping

      protected static final PluginParameter<String> internalIdColumnMapping

    • nameColumnMapping

      protected static final PluginParameter<String> nameColumnMapping

    • idAnnotationColumnMapping

      protected static final PluginParameter<String> idAnnotationColumnMapping
      Column mapping parameter for the annotation column used for item identification.
      Since:
      3.15

    • subtypeColumnMapping

      protected static final PluginParameter<String> subtypeColumnMapping

    • descriptionColumnMapping

      protected static final PluginParameter<String> descriptionColumnMapping

    • externalIdColumnMapping

      protected static final PluginParameter<String> externalIdColumnMapping

    • registeredColumnMapping

      protected static final PluginParameter<String> registeredColumnMapping
      Column mapping parameter for the item registration date.
      Since:
      3.11

    • protocolColumnMapping

      protected static final PluginParameter<String> protocolColumnMapping

    • kitColumnMapping

      protected static final PluginParameter<String> kitColumnMapping

    • permissionTemplateColumnMapping

      protected static final PluginParameter<String> permissionTemplateColumnMapping

    • itemNotFoundErrorParameter

      private static final PluginParameter<String> itemNotFoundErrorParameter

    • itemExistsErrorParameter

      private static final PluginParameter<String> itemExistsErrorParameter

    • multipleItemsFoundErrorParameter

      private static final PluginParameter<String> multipleItemsFoundErrorParameter

    • referenceNotFoundErrorParameter

      private static final PluginParameter<String> referenceNotFoundErrorParameter

    • multipleReferencesFoundErrorParameter

      private static final PluginParameter<String> multipleReferencesFoundErrorParameter

    • noWritePermissionToItemErrorParameter

      private static final PluginParameter<String> noWritePermissionToItemErrorParameter

    • noUsePermissionToReferenceErrorParameter

      private static final PluginParameter<String> noUsePermissionToReferenceErrorParameter

    • dc

      private DbControl dc

    • activeProject

      private Project activeProject

    • ffp

      private FlatFileParser ffp

    • dateFormatter

      private Formatter<Date> dateFormatter

    • idMethod

      private IdMethod idMethod

    • idMapping

      private String idMapping

    • idMapper

      private Mapper idMapper

    • permissionTemplateMapper

      private Mapper permissionTemplateMapper

    • subtypeMapper

      private Mapper subtypeMapper

    • selectedSubtype

      private ItemSubtype selectedSubtype

    • itemQuery

      private ItemQuery<I extends BasicItem> itemQuery

    • itemList

      private ItemList itemList

    • updateMode

      boolean updateMode

    • createMode

      boolean createMode

    • addMembersMode

      boolean addMembersMode

    • removeMembersMode

      boolean removeMembersMode

    • lastIdentifier

      private String lastIdentifier

    • lastItem

      private I extends BasicItem lastItem

    • numMultiLines

      private int numMultiLines

    • skippedLast

      private boolean skippedLast

    • dryRun

      private boolean dryRun

    • errorHandler

      private ClassMapErrorHandler errorHandler

    • cropStrings

      private boolean cropStrings

    • createNotFoundItems

      private boolean createNotFoundItems

    • failIfNotFoundItems

      private boolean failIfNotFoundItems

    • updateExistingItems

      private boolean updateExistingItems

    • failIfItemExists

      private boolean failIfItemExists

    • failIfMultipleFoundItems

      private boolean failIfMultipleFoundItems

    • failIfNotFoundReference

      private boolean failIfNotFoundReference

    • failIfMultipleFoundReferences

      private boolean failIfMultipleFoundReferences

    • failIfNoWritePermissionToItem

      private boolean failIfNoWritePermissionToItem

    • failIfNoUsePermissionToReference

      private boolean failIfNoUsePermissionToReference

    • numUpdated

      private int numUpdated

    • numCreated

      private int numCreated

    • numError

      private int numError

    • numNotFound

      private int numNotFound

    • numExisted

      private int numExisted

    • subtypeQuery

      private ItemQuery<ItemSubtype> subtypeQuery

    • protocolQuery

      private ItemQuery<Protocol> protocolQuery

    • kitQuery

      private ItemQuery<Kit> kitQuery

    • tagQuery

      private ItemQuery<Tag> tagQuery

    • hardwareQuery

      private ItemQuery<Hardware> hardwareQuery

    • softwareQuery

      private ItemQuery<Software> softwareQuery

    • annotationTypeCategoryQuery

      private ItemQuery<AnnotationTypeCategory> annotationTypeCategoryQuery

    • unitQuery

      private ItemQuery<Unit> unitQuery

    • platformQuery

      private ItemQuery<Platform> platformQuery

    • variantQuery

      private ItemQuery<PlatformVariant> variantQuery

    • fileTypeQuery

      private ItemQuery<DataFileType> fileTypeQuery

    • permissionTemplateQuery

      private ItemQuery<PermissionTemplate> permissionTemplateQuery

    • bioSourceQuery

      private ItemQuery<BioSource> bioSourceQuery

    • sampleQuery

      private ItemQuery<Sample> sampleQuery

    • extractQuery

      private ItemQuery<Extract> extractQuery

    • labeledExtractQuery

      private ItemQuery<Extract> labeledExtractQuery

    • bioPlateQuery

      private ItemQuery<BioPlate> bioPlateQuery

    • arraySlideQuery

      private ItemQuery<ArraySlide> arraySlideQuery

    • hybQuery

      private ItemQuery<PhysicalBioAssay> hybQuery

    • physicalBioAssayQuery

      private ItemQuery<PhysicalBioAssay> physicalBioAssayQuery

    • derivedBioAssayQuery

      private ItemQuery<DerivedBioAssay> derivedBioAssayQuery

    • designQuery

      private ItemQuery<ArrayDesign> designQuery

    • batchQuery

      private ItemQuery<ArrayBatch> batchQuery

    • geometryQuery

      private ItemQuery<PlateGeometry> geometryQuery

    • bioPlateTypeQuery

      private ItemQuery<BioPlateType> bioPlateTypeQuery

    • fileServerQuery

      private ItemQuery<FileServer> fileServerQuery

    • fileCache

      private Set<String> fileCache

    • itemCache

      private Map<String,BasicItem> itemCache
      Cache that holds loaded/created items. The cache key is item type + identifier, eq. SAMPLE:My sample, EXTRACT:An extract. The same item may be cached under more than one key depending on which identifier has been used to look it up, eg name, id, etc.: SAMPLE:My sample, SAMPLE:10.

    • configureParser

      private RequestInformation configureParser

    • configureOptions

      private RequestInformation configureOptions

  • Constructor Details

    • AbstractItemImporter

      public AbstractItemImporter()

  • Method Details

    • requiresConfiguration

      public boolean requiresConfiguration()
      Description copied from class: AbstractFlatFileImporter
      Return TRUE, since the implementation requires it for finding the regular expressions used by the FlatFileParser. If this method is overridden and returns FALSE, the subclass must also override the AbstractFlatFileImporter.getInitializedFlatFileParser() method and provide a parser with all regular expressions and other options set.
      Specified by:
      requiresConfiguration in interface Plugin
      Overrides:
      requiresConfiguration in class AbstractFlatFileImporter
      Returns:
      TRUE or FALSE

    • supportsConfigurations

      public boolean supportsConfigurations()
      Description copied from class: AbstractPlugin
      Returns TRUE, since that is how the plugins used to work before this method was introduced.
      Specified by:
      supportsConfigurations in interface Plugin
      Overrides:
      supportsConfigurations in class AbstractPlugin
      Returns:
      TRUE or FALSE

    • isInContext

      public String isInContext(GuiContext context, Object item)
      Description copied from interface: InteractivePlugin
      Check if the plugin can be used on the specified object. The item is either a BasicItem or BasicData object, or null if called from a list context. A client application should only call this method for contexts matching one of the contexts in the set returned by the InteractivePlugin.getGuiContexts() method. For GuiContext.Type.ITEM contexts an item of the correct type should be passed as a parameter.

      The plug-in can response with a null value indicating success, a warning-level message or throw an exception to indicate an error-level message. Client application should normally only show error-level messages to users, unless the user has requested to see warning messages.

      NOTE! Before BASE 2.4 all messages were treated as error-level messages.

      Specified by:
      isInContext in interface InteractivePlugin
      Parameters:
      context - The current context of the client application, it is one of the values found in set returned by InteractivePlugin.getGuiContexts()
      item - The currently active item, it's type should match the GuiContext.getItem() type, or null if the context is a list context
      Returns:
      Null if the plugin can use that item, or a warning-level message explaining why the plugin can't be used

    • configure

      public void configure(GuiContext context, Request request, Response response)
      Description copied from interface: InteractivePlugin
      Configure the plugin. Hopefully the client is supplying values for the parameters specified by InteractivePlugin.getRequestInformation(GuiContext, String).
      Specified by:
      configure in interface InteractivePlugin
      Parameters:
      context - The current context of the client application, it is one of the values found in set returned by InteractivePlugin.getGuiContexts()
      request - Request object with the command and parameters
      response - Response object in for the plugin to response through

    • getRequestInformation

      public RequestInformation getRequestInformation(GuiContext context, String command) throws BaseException
      Description copied from interface: InteractivePlugin
      This method will return the RequestInformation for a given command, i.e. the list of parameters and some nice help text.
      Specified by:
      getRequestInformation in interface InteractivePlugin
      Parameters:
      context - The current context of the client application, it is one of the values found in set returned by InteractivePlugin.getGuiContexts()
      command - The command
      Returns:
      The RequestInformation for the command
      Throws:
      BaseException - if there is an error

    • setUpErrorHandling

      protected void setUpErrorHandling()
      Don't use AbstractFlatFileImporter to handle errors.
      Overrides:
      setUpErrorHandling in class AbstractFlatFileImporter

    • begin

      protected void begin(FlatFileParser ffp)
      Setup error handling and pre-load some of the configuration options.
      Overrides:
      begin in class AbstractFlatFileImporter
      See Also:

    • beginData

      protected void beginData()
      Setup column mapping. Creates DbControl and query to find items.
      Overrides:
      beginData in class AbstractFlatFileImporter

    • handleData

      protected void handleData(FlatFileParser.Data data) throws BaseException
      Description copied from class: AbstractFlatFileImporter
      Called by the parser for every line in the file that is a data line.
      Specified by:
      handleData in class AbstractFlatFileImporter
      Throws:
      BaseException

    • end

      protected void end(boolean success)
      Description copied from class: AbstractFlatFileImporter
      Called just after the last line of the file has been parsed, or immediately after an error has ocurred. A subclass should clean up any resources aquired in the AbstractFlatFileImporter.begin(FlatFileParser) method here. Note that this metod is called once for every file returned by the AbstractFlatFileImporter.getFileIterator() iterator.
      Overrides:
      end in class AbstractFlatFileImporter
      Parameters:
      success - TRUE if the file was parsed successfully, FALSE otherwise
      See Also:

    • getSuccessMessage

      protected String getSuccessMessage(int skippedLines)
      Description copied from class: AbstractFlatFileImporter
      Called if the parsing was successful to let the subclass generate a simple message that is sent back to the core and user interface. An example message might by: 178 reporters imported successfully. The default implementation always return null. Note that this method is called once for every file returned by AbstractFlatFileImporter.getFileIterator().
      Overrides:
      getSuccessMessage in class AbstractFlatFileImporter
      Parameters:
      skippedLines - The number of data lines that were skipped due to errors

    • getIdMethods

      protected IdMethod[] getIdMethods()
      Get an array with all identification methods that can be used to find items. The default implementation returns an array with the PropertyIdMethod.NAME, InternalIdMethod.INTERNAL_ID and FallbackIdMethod.NAME_OR_ID ID methods. Subclasses that import items that can use other ID methods, should override this method.

    • getAnnotationIdMethods

      protected List<IdMethod> getAnnotationIdMethods(DbControl dc)
      Get identification methods that are based on annotations. The default implementation first calls the getItemForAnnotationTypes(). If this returns a non-null value it will make a query for all annotation types that are suitable as identifiers: The value type must be one of STRING, INT or LONG It must not be an enumeration The 'identifier' flag must be set
      Since:
      3.15

    • addMoreJobParameters

      protected void addMoreJobParameters(List<PluginParameter<?>> parameters)
      Add extra job parameters that the subclass needs. This method is called during configuration of the plug-in and the default implementation does nothing.
      Parameters:
      parameters - The list of parameters to add the column mapping parameters to

    • addMoreParsingParameters

      protected void addMoreParsingParameters(List<PluginParameter<?>> parameters)
      Add extra parameters to the "Parser settings" section that the subclass needs. This method is called during configuration of the plug-in and the default implementation does nothing.
      Parameters:
      parameters - The list of parameters to add the column mapping parameters to

    • addMoreColumnMappingParameters

      protected void addMoreColumnMappingParameters(List<PluginParameter<?>> parameters)
      Add column mapping parameters for item-specific properties. A subclass must add parameters for all properties, including name and description. This class has already created some useful parameters for this purpose, for example: nameColumnMapping and descriptionColumnMapping. This method is called during configuration of the plug-in.
      Parameters:
      parameters - The list of parameters to add the column mapping parameters to

    • addMoreErrorParameters

      protected void addMoreErrorParameters(List<PluginParameter<?>> parameters)
      Add extra parameters to the "Error handling" section that the subclass needs. This method is called during configuration of the plug-in and the default implementation does nothing.
      Parameters:
      parameters - The list of parameters to add the column mapping parameters to

    • createItemQuery

      protected ItemQuery<I> createItemQuery(ItemList list)
      Create a new query that returns items that are members of the given list. The default implementation calls createItemQuery() and then applies a restriction to it if the list is not null and have the same member type as the query.
      Since:
      3.15

    • createItemQuery

      protected abstract ItemQuery<I> createItemQuery()
      Create a new query that returns items of the importable type. The query should be a plain query not including any restrictions or other elements. This will automatically be added as needed by the core implementation. This method is called during execution of the plug-in. Typically, the result from getQuery() should be returned, eg. Sample.getQuery().
      Returns:
      A query

    • getItemForSubtypes

      protected Item getItemForSubtypes()
      Does the importer want to use item subtypes when importing? If this method returns a non-null, this class will add a parameter in the "Item identification" section that makes it possible to select which subtypes the importer should use to limit the search for existing items. The default implementation returns null.
      Returns:
      An Item or null

    • getItemForAnnotationTypes

      protected Item getItemForAnnotationTypes()
      Does the importer want to use annotation types as identifiers importing? If this method returns a non-null, this class will add all annotation types from the getAnnotationIdMethods(DbControl) to the ID method parameter. The subclass must also add the idAnnotationColumnMapping to the addMoreColumnMappingParameters(List) method. The default implementation returns null.
      Returns:
      An Item or null
      Since:
      3.15

    • createColumnMappers

      protected void createColumnMappers(FlatFileParser ffp, boolean cropStrings)
      Create mappers that can be used to extract data values from the file that is currently being parsed by the ffp FlatFileParser. This method is called during initialisation of the plug-in when the FlatFileParser.parseHeaders() has successfully found the start of data. Use the AbstractFlatFileImporter.getMapper(FlatFileParser, String, Integer, Mapper) to create column mappers. Example: 
      nameMapper = getMapper(ffp, job.getValue("nameColumnMapping"), 
   cropStrings ? Nameable.MAX_NAME_LENGTH : null, null);
      Parameters:
      ffp - The parser that is parsing the data file
      cropStrings - If strings that are too long to fit in the database should be cropped or not (=generate an error)

    • createItem

      protected abstract I createItem(DbControl dc, FlatFileParser.Data data)
      Create a new item and populate it with data from the current line. Do not call DbControl.saveItem(BasicItem). This is done automatically by the core implementation. 
      BioSource bs = BioSource.getNew(dc);
// Set properties. See example on updateItem method
return bs;

      If the current data line doesn't have data for all required properties, this method should throw an InvalidUseOfNullException exception.

      This method is called during import when current item can be found and if the user has selected to create missing item.

      Parameters:
      dc - The DbControl to use for database access
      data - The current data line
      Returns:
      A new item

    • updateItem

      protected abstract void updateItem(DbControl dc, I item, FlatFileParser.Data data)
      Update an item with data from the current line. Example: 
      if (nameMapper != null) item.setName(nameMapper.getValue(data));
if (descriptionMapper != null) item.setDescription(descriptionMapper.getValue(data));
...
      This method is called during import to update an existing item.
      Parameters:
      dc - The DbControl to use for database access
      item - The item to update
      data - The current data line

    • updateMultiLineItem

      protected void updateMultiLineItem(DbControl dc, I item, FlatFileParser.Data data, int multiLineNum)
      Update an item with data from a multi-line entry. Items which can have multiple parents should have data for the other parents on lines following the first line.
      Parameters:
      dc - The DbControl to use for database access
      item - The item to update
      data - The current data line
      multiLineNum - The number of the multi-line entry, starting with 1 for the first multi-line

    • doneWithItem

      protected void doneWithItem(DbControl dc, I item, int numMultiLines)
      Called when the importer is finished with an item. This method is useful when working with multi-line entries, when the subclass needs to do some additional work after all data has been set. NOTE! This assumes that the lines in the data file are sorted in the correct order and the no lines for the same item will follow later on.
      Parameters:
      dc - The DbControl to use for database access
      item - The item to update
      numMultiLines - The number of the multi-line entries, starting with 1 for the first multi-line (0 for single-line entries)

    • updatePermissions

      protected void updatePermissions(DbControl dc, Shareable item, FlatFileParser.Data data, boolean merge)
      If a mapping for a permission template has been specified for the job, this method is automatically called. It will merge or replace the permissions on the item with the permissions from the template.
      Parameters:
      dc - A DbControl used to lookup the permission template
      item - The item to update
      data - Data from the file
      merge - TRUE to merge the permissions, FALSE to replace the permissions
      Since:
      2.16

    • updateItemSubtype

      protected void updateItemSubtype(DbControl dc, Subtypable item, FlatFileParser.Data data)
      If a mapping for item subtype has been specified or if a single subtype was selected for item identification in this job, this method is will update the subtype on the item.
      Parameters:
      dc - A DbControl used to lookup the subtype
      item - The item to update
      data - Data from the file
      Since:
      3.0

    • findItemSubtype

      protected ItemSubtype findItemSubtype(DbControl dc, Item mainItemType, FlatFileParser.Data data)
      Try to find subtype from the given file data. If a single subtype was selected for item identification in this job, that subtype is used if no mapped subtype can be found.
      Parameters:
      dc - A DbControl used to lookup the subtype
      mainItemType - The main item type of the subtype
      data - Data from the file
      Returns:
      A subtype of null if no subtype could be found
      Since:
      3.0

    • getDefaultItemFunction

      protected <T extends Nameable> DefaultItemFunction<T> getDefaultItemFunction(Item itemType)
      Create a DefaultItemFunction for the given item type. The currently active project (if any) is used.
      Parameters:
      itemType - The type of items the function should look for
      Since:
      3.1

    • getIdMethod

      protected IdMethod getIdMethod(DbControl dc, String method)
      Get the id method to use for finding items. This implementation searches the methods returned by getIdMethods() and getAnnotationIdMethods(DbControl) for a method with the given name. If no method can be found PropertyIdMethod.NAME is returned.

    • parseDate

      @Deprecated protected Date parseDate(String date)
      Deprecated.
      In 3.15, use FlatFileParser.getDateMapper(String) or FlatFileParser.getTimestampMapper(String) and Mapper.getDate(FlatFileParser.Data) instead
      Parse a string to a date using the date format specified by the 'Date format' parameter. This is a utility method that subclasses can use to extract date values, since the Mapper interface doesn't supports it.

    • findItemSubtype

      protected ItemSubtype findItemSubtype(DbControl dc, IdMethod idMethod, Item mainType, String identifier)
      Find an item subtype with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier for the subtype
      mainType - The main item type for the subtype
      Returns:
      A subtype, or null if no item could be found
      Since:
      3.0

    • findProtocol

      protected Protocol findProtocol(DbControl dc, IdMethod idMethod, String identifier)
      Same as findProtocol(DbControl, IdMethod, String, ItemSubtype) with a null item subtype.

    • findProtocol

      protected Protocol findProtocol(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a protocol with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no protocol is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The protocol subtype, or null if the type doesn't matter
      Returns:
      A protocol, or null if no item could be found
      Since:
      3.0

    • findKit

      protected Kit findKit(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a kit with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no kit is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The kit subtype, or null if the type doesn't matter
      Returns:
      A kit, or null if no item could be found
      Since:
      3.7

    • findTag

      protected Tag findTag(DbControl dc, IdMethod idMethod, String identifier)
      Same as findTag(DbControl, IdMethod, String, ItemSubtype) with a null item subtype.

    • findTag

      protected Tag findTag(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a tag with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no hardware is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The tag subtype, or null if the type doesn't matter
      Returns:
      A tag, or null if no item could be found
      Since:
      3.0

    • findHardware

      protected Hardware findHardware(DbControl dc, IdMethod idMethod, String identifier)
      Same as findHardware(DbControl, IdMethod, String, ItemSubtype) with a null item subtype.

    • findHardware

      protected Hardware findHardware(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a hardware with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no hardware is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The hardware subtype, or null if the type doesn't matter
      Returns:
      A hardware, or null if no item could be found
      Since:
      3.0

    • findSoftware

      protected Software findSoftware(DbControl dc, IdMethod idMethod, String identifier)
      Same as findSoftware(DbControl, IdMethod, String, ItemSubtype) with a null item subtype.

    • findSoftware

      protected Software findSoftware(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a software with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no software is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The software subtype, or null if the type doesn't matter
      Returns:
      A software, or null if no item could be found
      Since:
      3.0

    • findAnnotationTypeCategory

      protected AnnotationTypeCategory findAnnotationTypeCategory(DbControl dc, IdMethod idMethod, String identifier)
      Find an annotation type category with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      An annotation type category, or null if no item could be found
      Since:
      3.8

    • findUnit

      protected Unit findUnit(DbControl dc, IdMethod idMethod, String identifier)
      Find a unit with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A unit, or null if no item could be found
      Since:
      3.8

    • findPlatform

      protected Platform findPlatform(DbControl dc, IdMethod idMethod, String identifier)
      Find a platform with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A platform, or null if no item could be found

    • getProjectDefaultPlatform

      protected Platform getProjectDefaultPlatform(DbControl dc)
      Get the default platform of the currently active project. If there is more than one default platform, the first one is selected.
      Returns:
      The active platform, or null if no project is active or the project doesn't specify a platform
      Since:
      2.9

    • getProjectDefaultVariant

      protected PlatformVariant getProjectDefaultVariant(DbControl dc)
      Get the default platform variant of the currently active project.
      Returns:
      The active platform variant, or null if no project is active or the project doesn't specify a variant
      Since:
      2.9

    • findVariant

      protected PlatformVariant findVariant(DbControl dc, Platform platform, IdMethod idMethod, String identifier)
      Find a platform variant with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      platform - If given, searched only variants of this platform
      identifier - The identifier protocol
      Returns:
      A platform, or null if no item could be found

    • getProjectDefaultRawDataType

      protected RawDataType getProjectDefaultRawDataType(DbControl dc)
      Get the default raw data type of the currently active project.
      Returns:
      The active raw data type, or null if no project is active or the project doesn't specify raw data type
      Since:
      2.9

    • findDataFileType

      protected DataFileType findDataFileType(DbControl dc, IdMethod idMethod, String identifier)
      Find a data file type with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A data file, or null if no item could be found

    • findPermissionTemplate

      protected PermissionTemplate findPermissionTemplate(DbControl dc, IdMethod idMethod, String identifier)
      Find a permission template with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier for the template
      Returns:
      A permission template, or null if no item could be found

    • findBioSource

      protected BioSource findBioSource(DbControl dc, IdMethod idMethod, String identifier)
      Same as findBioSource(DbControl, IdMethod, String, ItemSubtype) with a null item subtype.

    • findBioSource

      protected BioSource findBioSource(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a biosource with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no biosource is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The biosource subtype, or null if the type doesn't matter
      Returns:
      A biosource, or null if no item could be found
      Since:
      3.0

    • findSample

      protected Sample findSample(DbControl dc, IdMethod idMethod, String identifier)
      Same as findSample(DbControl, IdMethod, String, ItemSubtype) with a null subtype.

    • findSample

      protected Sample findSample(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a sample with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no sample is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The sample subtype, or null if the type doesn't matter
      Returns:
      A sample, or null if no item could be found
      Since:
      3.0

    • findExtract

      protected Extract findExtract(DbControl dc, IdMethod idMethod, String identifier)
      Same as findSample(DbControl, IdMethod, String, ItemSubtype) with a null subtype.

    • findExtract

      protected Extract findExtract(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find an extract with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no extract is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The extract subtype, or null if the type doesn't matter
      Returns:
      An extract, or null if no item could be found
      Since:
      3.0

    • findLabeledExtract

      protected Extract findLabeledExtract(DbControl dc, IdMethod idMethod, String identifier)
      Find a labled extract with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! A labeled extract is an extract with a subtype Extract.LABELED

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A labeled extract, or null if no item could be found

    • findBioPlate

      protected BioPlate findBioPlate(DbControl dc, IdMethod idMethod, String identifier)
      Find a bioplate with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A bioplate, or null if no item could be found

    • findBioWell

      protected BioWell findBioWell(DbControl dc, BioPlate plate, String row, String column)
      Find a well on a bioplate. Null is allowed for all parameters but will always result in a null return value.
      Parameters:
      dc - The DbControl to use for database access
      plate - The plate to look on
      row - The row coordinate in alphabetic or 1-based values
      column - The column coordinate in alphabetic or 1-based values
      Returns:
      A biowell, or null if no item could be found
      Since:
      2.16

    • findArraySlide

      protected ArraySlide findArraySlide(DbControl dc, IdMethod idMethod, String identifier)
      Find an array slide with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      An array slide, or null if no item could be found

    • findHybridization

      protected PhysicalBioAssay findHybridization(DbControl dc, IdMethod idMethod, String identifier)
      Find a hybridization with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! A hybridization is a physical bioassay with a subtype PhysicalBioAssay.HYBRIDIZATION

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A hybridization, or null if no item could be found

    • findPhysicalBioAssay

      protected PhysicalBioAssay findPhysicalBioAssay(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a physical bioassay with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no bioassay is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The bioassay subtype, or null if the type doesn't matter
      Returns:
      A physical bioassay, or null if no item could be found
      Since:
      3.0

    • findDerivedBioAssay

      protected DerivedBioAssay findDerivedBioAssay(DbControl dc, IdMethod idMethod, String identifier, ItemSubtype subtype)
      Find a derived bioassay with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      NOTE! If this method is called with a non-null item subtype parameter and no bioassay is found the query will be retried without any subtype.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      subtype - The bioassay subtype, or null if the type doesn't matter
      Returns:
      A derived bioassay, or null if no item could be found
      Since:
      3.0

    • findArrayDesign

      protected ArrayDesign findArrayDesign(DbControl dc, IdMethod idMethod, String identifier)
      Find an array design with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      An array design, or null if no item could be found

    • findArrayBatch

      protected ArrayBatch findArrayBatch(DbControl dc, IdMethod idMethod, String identifier)
      Find an array batch with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      An array batch, or null if no item could be found

    • findPlateGeometry

      protected PlateGeometry findPlateGeometry(DbControl dc, IdMethod idMethod, String identifier)
      Find a plate geometry with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A plate geometry, or null if no item could be found
      Since:
      2.16

    • findBioPlateType

      protected BioPlateType findBioPlateType(DbControl dc, IdMethod idMethod, String identifier)
      Find a bioplate type with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A bioplate type, or null if no item could be found
      Since:
      2.16

    • findRawDataType

      protected RawDataType findRawDataType(DbControl dc, Platform platform, PlatformVariant variant, String identifier)
      Find a matching raw data type. This method will look in the following order:
      1. The raw data type locked to the platform variant: PlatformVariant.getRawDataType()
      2. The raw data type locked to the platform: Platform.getRawDataType()
      3. Any registered raw data type with the given 'id': RawDataTypes.getRawDataType(String)
      4. Any registered raw data type with the given 'name': RawDataTypes.getRawDataTypes()
      5. The project default raw data type: getProjectDefaultRawDataType(DbControl)
      If a raw data type is found by a check, the remaining checks are ignored. If no item is found or if multiple items are found (in the 'name' lookup) the settings (failIfMultipleFoundReferences and failIfNotFoundReference) determine if an exception is thrown or not.
      Parameters:
      platform - The current platform or null to not use a platform for lookup
      variant - The current platform variant or null to not use a variant for lookup
      identifier - The 'id' or 'name' of a raw data type, or null to not use this for lookup
      Returns:
      A raw data type or null if not found
      Since:
      2.15

    • findFileServer

      protected FileServer findFileServer(DbControl dc, IdMethod idMethod, String identifier)
      Find a file server with a given identifier. This is a utility method that subclasses can use when creating or updating items.

      NOTE! The first time this method is called a query object is initialised using the IdMethod.prepareQuery(DbControl, ItemQuery) method. Subsequent calls uses the same query. Thus, this method should always be called with the same id method object, otherwise the result is undefined.

      Parameters:
      dc - The DbControl to use for database access
      identifier - The identifier protocol
      Returns:
      A file server, or null if no item could be found
      Since:
      3.3

    • setOrAddFile

      protected FileSetMember setOrAddFile(FileStoreEnabled item, DataFileType fileType, File file)
      Set or add a file to a file set. The first time this method is called for a given item and file type combination FileSet.setMember(File, DataFileType) is used to add the file to the file set (which will replace all other files of the same file type. If this method is called more times then FileSet.addMember(File, DataFileType) is used so that already added files are preserved. If the file is null the first time, all files of the given file types are removed. If the file is null after the first time, this call is ignored.
      Parameters:
      item - The item to set/add a file to
      fileType - The type of the file
      file - The file, or null
      Returns:
      The new member entry, or null if the call didn't result in an addition
      Since:
      3.0

    • initReferenceQuery

      protected <T extends BasicItem> ItemQuery<T> initReferenceQuery(DbControl dc, IdMethod idMethod, ItemQuery<T> query, boolean subtype)
      Initialise a query that is used to find referenced items. This method delegates to IdMethod.prepareQuery(DbControl, ItemQuery) and then adds Include options: MINE, IN_PROJECT, SHARED and OTHERS.
      Parameters:
      dc - A DbControl used for database access
      idMethod - The identification method to use
      query - The query to initialised
      subtype - If TRUE a restriction for subtype is added to the query
      Returns:
      The initialised query

    • findReferencedItemWithSubtype

      protected <T extends BasicItem> T findReferencedItemWithSubtype(DbControl dc, IdMethod idMethod, ItemQuery<T> query, String identifier, ItemSubtype subtype, boolean ignoreNotFound)
      Find a referenced item with a subtype. This method may call the findReferencedItem(DbControl, IdMethod, ItemQuery, String, int, boolean) method two times. First, with a query limited to return items of the given subtype, then a second time without the limit. The query must have been created by the initReferenceQuery(DbControl, IdMethod, ItemQuery, boolean) method with TRUE for the last parameter. If the subtype parameter is null the first query is skipped.

    • findReferencedItem

      protected <T extends BasicItem> T findReferencedItem(DbControl dc, IdMethod idMethod, ItemQuery<T> query, String identifier, int subtypeId, boolean ignoreNotFound)
      Find a referenced item. This method will first look in the itemCache. If no item is found in the cache it uses the query and id method (IdMethod.find(DbControl, ItemQuery, String)) to look for the item. The result of the lookup is stored in the cache (even if no item is found).
      Parameters:
      dc - A DbControl used for database access
      idMethod - The identification method
      ignoreNotFound - TRUE to ignore not found errors
      Returns:
      The item, or null if none is found
      Throws:
      ItemNotFoundException - If no item is found and the error handling is set to fail for this condition
      BaseException - If multiple items are found and the error handling is set to fail for this condition

    • getItemListFromContext

      private ItemList getItemListFromContext(DbControl dc, GuiContext context)
      If the current context is the "Members" tab for an item list we load the item list and will later require that all items to be annotated are members of that list.

    • getConfigureParserParameters

      protected RequestInformation getConfigureParserParameters(GuiContext context, boolean forJob)

    • getConfigureOptionsParameters

      protected RequestInformation getConfigureOptionsParameters(GuiContext context)