Class AnnotationType

  • All Implemented Interfaces:
    AccessControlled, Identifiable, Nameable, Ownable, Registered, Removable, Shareable

    public class AnnotationType
    extends CommonItem
    implements Registered
    Objects of this class defines an annotation type. An annotation type is always of a specific Type, ie. a string, integer, etc. Limitations on the values can be specified, ie. min and max values, max string length, etc. It is also possible to use a predefined list of allowed values, ie an enumeration.

    An annotation type also specifies which types of items it can be used on.

    Version:
    2.0
    Author:
    Nicklas
    See Also:
    Annotatable, Annotation
    Last modified
    $Date: 2019-08-08 09:21:14 +0200 (tors, 08 aug. 2019) $
    • Field Detail

      • MAX_EXTERNAL_ID_LENGTH

        public static final int MAX_EXTERNAL_ID_LENGTH
        The maximum length of the external id that can be stored in the database.
        Since:
        2.2
        See Also:
        setExternalId(String), Constant Field Values
      • MAX_DEFAULT_VALUE_LENGTH

        public static final int MAX_DEFAULT_VALUE_LENGTH
        The maximum length of the default value.
        See Also:
        Constant Field Values
      • MAX_OPTION_LENGTH

        public static final int MAX_OPTION_LENGTH
        The maximum length of an option.
        See Also:
        Constant Field Values
    • Method Detail

      • getNew

        public static AnnotationType getNew​(DbControl dc,
                                            Type valueType)
                                     throws BaseException
        Create a new AnnotationType item.
        Parameters:
        dc - The DbControl which will be used for permission checking and database access
        valueType - The type of values to use
        Returns:
        The new AnnotationType item
        Throws:
        BaseException - If there is an error
      • getQuery

        public static ItemQuery<AnnotationType> getQuery​(Item itemType)
        Get a ItemQuery that returns annotation types. If the itemType parameter is null, annotation types for all item types will be returned
        Parameters:
        itemType - Optional, limit the annotation types to those that are enabled for the specified item
        Returns:
        An ItemQuery object
      • getAllAnnotationTypesWithInheritanceDisabled

        public static Set<Integer> getAllAnnotationTypesWithInheritanceDisabled​(DbControl dc)
        Load the IDs of all annotation types with the disable inheritance flag set. This method will return all such IDs without checking permissions of the current user. The returned set is not modifiable.
        Since:
        3.5
      • getType

        public Item getType()
        Description copied from interface: Identifiable
        Get the type of item represented by the object. The returned value is one of the values defined in the Item enumeration.
        Specified by:
        getType in interface Identifiable
        Returns:
        A value indicating the type of item
      • getEntryDate

        public Date getEntryDate()
        Description copied from interface: Registered
        Get the date that the item was registered in the database.
        Specified by:
        getEntryDate in interface Registered
        Returns:
        A date or null if this is not known
      • setEntryDate

        public void setEntryDate​(Date entryDate)
        Description copied from interface: Registered
        Set the date the entry was registered in the database. Implementations should only allow this property to be set before the item is first stored in the database. The intention of this method is to facilitate export/import of data between server.
        Specified by:
        setEntryDate in interface Registered
        Parameters:
        entryDate - A date or null to use today's date
      • isUsed

        public boolean isUsed()
                       throws BaseException
        Checks if:
        • Annotations of this type exists
        • Experiments are using this annotation type as an experimental factor
        • Protocols are using this annotation type as a protocol parameter
        Overrides:
        isUsed in class BasicItem
        Returns:
        TRUE if this item is used, FALSE otherwise
        Throws:
        BaseException - If not able to tell if item is used or not.
        See Also:
        BasicItem.getUsingItems()
      • supportUnits

        public boolean supportUnits()
        Checks if this annotation types support units.
        Returns:
        TRUE if a unit is used, FALSE otherwise
        Since:
        2.9
      • getQuantity

        public Quantity getQuantity()
        Get the quantity for this annotation type. If the quantity is null, units are not used with this annotation type. An annotation type without units can be changed to use units with the setDefaultUnit(Unit) method. Once a unit has been configured, it is not possible to change the Quantity.
        Returns:
        The quantity, or null
        Since:
        2.9
      • getDefaultUnit

        public Unit getDefaultUnit()
        Get the default unit for this annotation type.
        Returns:
        The default unit, or null if this annotation type doesn't use units
        Since:
        2.9
      • setDefaultUnit

        public void setDefaultUnit​(Unit defaultUnit)
        Set the default unit to use for this annotation type. If the annotation type doesn't have any current default unit, any unit can be used. If there already is a default unit, the new unit must be from the same Quantity as the existing unit.

        Note! Changing units will result in a conversion of existing annotation values to the new unit. This may result in loss of precision due to rounding or truncation errors.

        Parameters:
        defaultUnit - The new default unit
        Since:
        2.9
      • getUsableUnits

        public ItemQuery<Unit> getUsableUnits()
        Get a query for returning the units that are considered "usable" for this annotation type. This is typically used by client applications to limit the list of choices in the graphical interface. If this query doesn't return any items, all units should be considered usable.
        Returns:
        A query
        Since:
        2.9
      • isUsableUnit

        public boolean isUsableUnit​(Unit unit)
        Checks if the given unit is a unit that has been specified as a "usable" unit for this annotation type.
        Parameters:
        unit - The unit to check
        Returns:
        TRUE if the unit is "usable", FALSE otherwise
        Since:
        2.9
      • addUsableUnit

        public void addUsableUnit​(Unit unit)
        Add a unit to be used with this annotation type. Note! This doesn't prevent other units (from the same Quantity) from being used. This is just a recommendation to allow client applications to limit the list of choices in the graphical interface.
        Parameters:
        unit - The unit to add
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission for the annotation type or use permission for the unit
        InvalidDataException - If the unit is null
        Since:
        2.9
      • removeUsableUnit

        public void removeUsableUnit​(Unit unit)
        Remove a unit from this annotation type. This will not affect already existing annotation with this unit.
        Parameters:
        unit - The unit to remove from the set of usable units
        Throws:
        PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for the annotation type
        InvalidDataException - If the unit is null
        Since:
        2.9
      • clearUsableUnits

        public void clearUsableUnits()
        Clear all units.
        Since:
        2.9
      • getExternalId

        public String getExternalId()
        Get the external id of the annotation type. This value can be used to link with information in external databases. It is not used by the BASE core and it doesn't have to be unique.
        Returns:
        The external id for the annotation type
        Since:
        2.2
      • isMember

        public boolean isMember​(AnnotationTypeCategory category)
        Checks if the annotation type is a member of a category.
        Parameters:
        category - The category to check
        Returns:
        TRUE if the annotation type is a member, FALSE otherwise
      • getCategories

        public ItemQuery<AnnotationTypeCategory> getCategories()
        Get a query that returns the categories an annotation type belongs to.
        Returns:
        An ItemQuery object
      • getValueType

        public Type getValueType()
        Get the value type for this annotation type. It can't be change once the object has been created.
        Returns:
        A Type constant
      • getMultiplicity

        public int getMultiplicity()
        Get the multiplicity. The multiplicity tells the core how many values an annotation of this annotation type may contain. The default is one. Zero denotes unlimited values.
        Returns:
        the multiplicity as an int.
      • setMultiplicity

        public void setMultiplicity​(int multiplicity)
                             throws PermissionDeniedException,
                                    InvalidDataException
        Set the multiplicity. The multiplicity tells the core how many values an annotation of this annotation type may contain. The default is one. Zero denotes unlimited values.
        Parameters:
        multiplicity - Multiplicity to set.
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        InvalidDataException - If the multiplicity is lower than zero
      • isRequiredForMiame

        public boolean isRequiredForMiame()
        Check an annotation of this annotation type required for an item to be compliant with the MIAME recommendation.
        Returns:
        TRUE if required, FALSE otherwise.
        See Also:
        MIAME
      • setRequiredForMiame

        public void setRequiredForMiame​(boolean required)
                                 throws PermissionDeniedException
        Set if an annotation of this annotation type is required for an item to be compliant with the MIAME recommendation.
        Parameters:
        required - Should be TRUE if required or FALSE if it is not.
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        See Also:
        MIAME
      • isEnumeration

        public boolean isEnumeration()
        Check if this annotation type provides a list of predefined allowed values.
        Returns:
        TRUE if it is provided, FALSE otherwise.
      • getDisplayAsList

        public boolean getDisplayAsList()
        Check if the enumeration values should be displayed as a selection list or as radio buttons/checkboxes by the client application. The client application may decide to use some other display format that better suits the situation.
        Returns:
        TRUE if it should be displayed as a selection list, FALSE if radio buttons/check-boxes.
      • setDisplayAsList

        public void setDisplayAsList​(boolean displayAsList)
                              throws PermissionDeniedException,
                                     InvalidDataException
        Set if the enumeration values should be displayed as a selection list or as radio buttons/checkboxes by the client application. The client application may decide to use some other display format that better suits the situation.
        Parameters:
        displayAsList - Set to TRUE to display as a selection list or set to FALSE to display as radio buttons/check-boxes.
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        InvalidDataException - Never
      • getHeight

        public int getHeight()
        Get the recommended height in characters a client application should use to render an input field for annotations of this annotation type. A client application is not required to use this value if it is not appropriate for the situation.
        Returns:
        Characters height as an int.
      • setHeight

        public void setHeight​(int height)
                       throws PermissionDeniedException,
                              InvalidDataException
        Set the recommended height in characters a client application should use to render an input field for annotations of this annotation type. A client application is not required to use this value if it is not appropriate for the situation.
        Parameters:
        height - The height in characters
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        InvalidDataException - If the height is less than one
      • getWidth

        public int getWidth()
        Get the recommended width in characters a client application should use to render an input field for annotations of this annotation type. A client application is not required to use this value if it is not appropriate for the situation.
        Returns:
        The width as an int.
      • setWidth

        public void setWidth​(int width)
                      throws PermissionDeniedException,
                             InvalidDataException
        Set the recommended width in characters a client application should use to render an input field for annotations of this annotation type. A client application is not required to use this value if it is not appropriate for the situation.
        Parameters:
        width - The width in characters
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        InvalidDataException - If the width is less than one
      • getDefaultValue

        public String getDefaultValue()
        Get the recommended default value for new annotations of this annotation type. It is not certain that the string represents a value that can be converted to the correct value type as specified by the getValueType() setting.
        Returns:
        Default value as a String.
      • isEnabledForItem

        public boolean isEnabledForItem​(Item itemType)
        Check if this annotation type can be used to annotate item of the specified type.
        Parameters:
        itemType - The Item type
        Returns:
        TRUE if annotations are possible, FALSE otherwise
      • getEnabledItems

        public Set<Item> getEnabledItems()
        Get the Item types this annotation type is enabled for.
        Returns:
        A Set of Item:s
      • setItemTypes

        public void setItemTypes​(Collection<Item> items)
        Enable the annotation type for all of the specified item and disable it for all other.
        Since:
        3.8
      • isProtocolParameter

        public boolean isProtocolParameter()
        If this annotation type is intended to be used as a protocol parameter or as a regular annotations.
        Returns:
        TRUE if the annotation type is a protocol parameter, FALSE if it is a regular annotation type
        Since:
        2.2
      • setProtocolParameter

        public void setProtocolParameter​(boolean isProtocolParameter)
                                  throws PermissionDeniedException
        Specify if this annotation type should be used as a protocol parameter or as a regular annotation type
        Parameters:
        isProtocolParameter - TRUE to use the annotation type as a protocol parameter, FALSE to use it as a regular annotation type
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        Since:
        2.2
      • isProtocolParameter

        public boolean isProtocolParameter​(Protocol protocol)
        Check if this annotation type is a parameter to the specified protocol. NOTE! This method doesn't use the value from the isProtocolParameter().
        Parameters:
        protocol - The protocol to check, null always return false
        Returns:
        TRUE if the annotation type is a parameter to the protocol, FALSE otherwise
        Since:
        2.2
        See Also:
        Protocol.isParameter(AnnotationType)
      • getDisableLogOfValues

        public boolean getDisableLogOfValues()
        If this flag is set, the change history logging will not include actual annotation values. Use this to prevent sensitive data from appearing in the log.
        Since:
        3.3
      • setDisableLogOfValues

        public void setDisableLogOfValues​(boolean disableLogOfValues)
                                   throws PermissionDeniedException
        If this flag is set, the change history logging will not include actual annotation values. Use this to prevent sensitive data from appearing in the log.
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        Since:
        3.3
      • getDisableInheritance

        public boolean getDisableInheritance()
        If this flag is set, annotations of this type can't be inherited to child items. Use this to prevent sensitive data from being used in other contexts.
        Since:
        3.5
      • setDisableInheritance

        public void setDisableInheritance​(boolean disableInheritance)
                                   throws PermissionDeniedException
        If this flag is set, annotations of this type can't be inherited to child items. Use this to prevent sensitive data from being used in other contexts. Changing this from FALSE to TRUE will automatically trigger a database action that remove all existing inherited annotations of this type.
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        Since:
        3.5
      • getProjectAnnotations

        public boolean getProjectAnnotations()
        If this flag is set, annotation values can be set per project. The active project as set by SessionControl.getActiveProjectId() controls which annotation values that are visible.
        Since:
        3.10
      • setProjectAnnotations

        public void setProjectAnnotations​(boolean projectAnnotations)
                                   throws PermissionDeniedException
        If this flag is set, annotation values can be set per project. The active project as set by SessionControl.getActiveProjectId() controls which annotation values that are visible. Note that it is not possible to change this flag from TRUE to FALSE if there are existing projec-specific annotations for this annotation type.
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        Since:
        3.10
      • isIdentifier

        public boolean isIdentifier()
        If this flag is set, annotation values are considered to be alternate identifiers for the items they belong to. But note that BASE will not check or prevent the same value from being used for more than one item.
        Since:
        3.15
      • countProjectSpecificAnnotations

        public long countProjectSpecificAnnotations()
        Count the number of project-specific annotations that exists for this annotation type. If this returns a non-zero value, it is not possible to turn off the project-specific annotations feature until all annotations are deleted.
        Returns:
        The number of project-specific annotations
        Since:
        3.10
      • getMinValueLong

        public Long getMinValueLong()
        Get the minumum allowed value for an Type.INT or Type.LONG annotation.
        Returns:
        The minimum allowed value or null if none has been specfied or if this annotation type hasn't an INT or LONG value type
      • getMaxValueLong

        public Long getMaxValueLong()
        Get the maximum allowed value for an Type.INT or Type.LONG annotation.
        Returns:
        The maximum allowed value or null if none has been specfied or if this annotation type hasn't an INT or LONG value type
      • getMinValueDouble

        public Double getMinValueDouble()
        Get the minumum allowed value for a Type.FLOAT or Type.DOUBLE annotation.
        Returns:
        The minimum allowed value or null if none has been specfied or if this annotation type hasn't a FLOAT or DOUBLE value type
      • getMaxValueDouble

        public Double getMaxValueDouble()
        Get the maximum allowed value for a Type.FLOAT or Type.DOUBLE annotation.
        Returns:
        The maximum allowed value or null if none has been specfied or if this annotation type hasn't a FLOAT or DOUBLE value type
      • getMaxLength

        public Integer getMaxLength()
        Get the maximum allowed string length for a Type.STRING annotation.
        Returns:
        The maximum allowed string length or null if none has been specfied or if this annotation type hasn't an STRING value type
      • getValues

        public <T> List<T> getValues()
                              throws BaseException
        Get the list of allowed values if this annotation type is an enumeration.
        Returns:
        A List with the allowed values or null if this annotation type is not an enumeration or no values has been specified
        Throws:
        BaseException - If there is an error
        See Also:
        isEnumeration()
      • findValue

        public String findValue​(String value,
                                boolean ignoreCase,
                                boolean trim)
        This method should be used on enumerated string annotation types to find a matching predefined string value, optionally ignoring case and white-space.
        Parameters:
        value - The value to look for
        ignoreCase - TRUE to ignore case
        trim - TRUE to trim white-space from the start and end of string
        Returns:
        The matching string, or null if not found or if the annotation isn't an enumeration of strings
        Since:
        2.4
      • getOption

        public String getOption​(String name)
        Get an option.
      • getIntOption

        Integer getIntOption​(String name,
                             Integer defaultValue)
        Get an option and convert the value to an integer. If the option doesn't exist or the value can't be converted, the default value is returned.
      • getLongOption

        Long getLongOption​(String name,
                           Long defaultValue)
        Get an option and convert the value to a long. If the option doesn't exist or the value can't be converted, the default value is returned.
      • getFloatOption

        Float getFloatOption​(String name,
                             Float defaultValue)
        Get an option and convert the value to a float. If the option doesn't exist or the value can't be converted, the default value is returned.
      • getDoubleOption

        Double getDoubleOption​(String name,
                               Double defaultValue)
        Get an option and convert the value to a double. If the option doesn't exist or the value can't be converted, the default value is returned.
      • getBooleanOption

        boolean getBooleanOption​(String name,
                                 boolean defaultValue)
        Get an option and convert the value to a boolean. If the option doesn't exist the default value is returned. If the option contains the string "true" (case ignored) true is returned, false otherwise.
      • validateAnnotationValue

        public Object validateAnnotationValue​(Object value,
                                              Unit unit)
                                       throws InvalidDataException
        Validate an annotation value that can be in a different unit than the default unit. We check the following:
        • The object is of the correct type, ie. Float if getValueType() returns Type.FLOAT, etc. NOTE! If a unit is specified it is only required that the value is a Number. It will automatically be converted to the correct class after unit conversion has taken place.
        • The value is within the min and max bouds if specified
        • A string value is not too long
        • The value exists in the predefined list if this annotation type is an enumeration
        Parameters:
        value - The object to be validated
        unit - The unit if the value, this parameter is ignored if the value type doesn't support units (eg. strings) or if the no default unit has been set for this annotation type
        Returns:
        The validated value which may have been converted to the default unit
        Throws:
        InvalidDataException - If the value object can not be used.
        Since:
        2.11