Class Annotation

  • All Implemented Interfaces:
    AccessControlled, Identifiable

    public class Annotation
    extends BasicItem
    This class represents an annotation. Annotations are user-defined properties that can be attached to Annotatable items. They can be very useful in the filtering and analysis process.

    An annotation must have an AnnotationType, which controls the type of and how many values that can be attached to an annotation.

    Version:
    2.0
    Author:
    Nicklas
    Last modified
    $Date: 2019-03-12 08:29:06 +0100 (tis, 12 mars 2019) $
    • Field Detail

      • disableATPermissionCheck

        private boolean disableATPermissionCheck
      • ignoreActiveProject

        private boolean ignoreActiveProject
    • Method Detail

      • getQuery

        static ItemQuery<Annotation> getQuery()
        Get a query configured to retrieve annotations. This query may return items which the logged in user doesn't have read permission to. At the moment there is no way to solve this problem.
        Returns:
        An ItemQuery object
      • 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.
        Returns:
        A value indicating the type of item
      • initPermissions

        void initPermissions​(int granted,
                             int denied)
                      throws BaseException
        READ permission is granted if the logged in user has READ permission on the associated item and annotation type. CREATE, WRITE and DELETE permissions are granted if the logged in user has WRITE permission on the associated item and USE permission on the annotation type. USE permission (needed for inheriting) is granted if the logged in user has USE permission on the associated item.
        Overrides:
        initPermissions in class BasicItem
        Parameters:
        granted - Permissions that have been granted by the subclass
        denied - Permissions that have been denied by the subclass
        Throws:
        BaseException - If the permissions couldn't be initialised
      • disableATPermissionCheck

        void disableATPermissionCheck()
      • setProjectId

        void setProjectId​(int projectId)
        Set the project that this annotation value should belong to. This will disable the automatic check that creates a new project-specific value when trying to change the default value and a project is active.
        Since:
        3.11
      • getLastUpdate

        public Date getLastUpdate()
        Get the date and time the values in this annotation was last updated.
        Since:
        2.14
      • belongsTo

        public boolean belongsTo​(AnnotationSet as)
        Check if this annotation belongs to the primaray annotations for a specified annotation set. This method is useful to check if an annotation has been inherited or not.
        Parameters:
        as - The annotation set to check
        Returns:
        TRUE if this annotation is a primary annotation of the specified annotation set, FALSE otherwise
        Since:
        2.10
      • getSource

        public Annotation.Source getSource()
        Get the annotation source.
        Since:
        3.6
      • getInheritedFrom

        public Annotation getInheritedFrom()
        Get the parent annotation if this is an inherited or cloned annotation. May return null for a cloned annotation if the parent annotation has been deleted.
        Since:
        3.6
      • isProjectSpecific

        public boolean isProjectSpecific()
        Is this annotation a project-specific annotation?
        Since:
        3.10
      • isIgnoringActiveProject

        public boolean isIgnoringActiveProject()
        Checks if this annotation is ignoring the currently active project. This affects how the setValuesIfDifferent(List, Unit) methods treats annotations that represents the default value for a project-specific annotation. If this method returns FALSE the default value is not modified. Instead, a new project-specific value for the currently active project is created (or the existing one is updated) If this method returns TRUE it is always this annotation that is modified.
        Returns:
        TRUE if ignoring the active project
        Since:
        3.11
      • getProjectId

        public int getProjectId()
        Get the ID of the project that this project-specicif annotation belongs to.
        Returns:
        A project ID or 0 if this annotation is not project-specific
        Since:
        3.10
      • getProject

        public Project getProject()
        Get the project that this project-specific annotation belongs to.
        Returns:
        A project or null if this annotation is not project-specific
        Since:
        3.10
      • isOverridingDefault

        public boolean isOverridingDefault()
        Is this (project-specific) annotation overriding a default value?
        Since:
        3.10
      • getDefaultAnnotation

        public Annotation getDefaultAnnotation()
        Get the default annotation that this project-specific annotation is overriding.
        Returns:
        The default annotation or null if this annotation is not overriding a default value
        Since:
        3.10
      • hasUnit

        public boolean hasUnit()
        Checks if the values in this annotation has a unit.
        Returns:
        TRUE if a unit is used, FALSE otherwise
        Since:
        2.9
      • getUnit

        public Unit getUnit()
        Get the unit used for the values in this annotation.
        Returns:
        A unit, or null if this annotation doesn't use units
        Since:
        2.9
      • getUnitConverter

        public UnitConverter getUnitConverter​(Unit unit)
        Get a converter for converting the values in this annotation to a specific unit.
        Parameters:
        unit - The unit to convert the values to, or null to convert the values to the unit specified by getUnit()
        Returns:
        A unit converter, or null if this annotation doesn't use units, or if the specified unit is the same as the default unit of the annotation type (see AnnotationType.getDefaultUnit()
        Since:
        2.9
      • getUnitFormatter

        public <T> Formatter<T> getUnitFormatter​(Formatter<T> parent,
                                                 Unit unit)
        Wrap a parent formatter with a formatter for units. NOTE! Values should be retrived with the same unit using getValues(Unit) to be correctly formatted with the returned formatter.
        Parameters:
        parent - The parent formatter, which should be of the correct type for the annotation values
        unit - The unit to use for formatting, or null to use the annotation's unit
        Returns:
        A formatter object
        Since:
        2.9
      • getUnitSymbol

        public String getUnitSymbol​(Unit unit)
        Shortcut for Unit.getDisplaySymbol(), but also checks the default unit of the annotation type.
        Parameters:
        unit - The unit to get the symbol for, or null to use the annotation's unit
        Returns:
        The unit symbol, or null if this annotation doesn't use units
        Since:
        2.9
      • getValueType

        public Type getValueType()
        Get the value type for this annotation type. It can't be change once the object has been created.
        Returns:
        Type value type as an enum.
        Since:
        2.2
      • getValues

        public <T> List<T> getValues()
                              throws BaseException
        Get the values this annotation contains. The values are of a Type appropriate for the given annotation type, ie. Integer object for an integer annotation type. All objects in the list are of the same type. If this is an annotation with units, the values are returned in the unit of the annotation type (AnnotationType.getDefaultUnit()). Use getValues(Unit) to get the values in a different unit, including the specific unit used on this annotation.
        Returns:
        A list of objects
        Throws:
        BaseException - If there is an error
        See Also:
        AnnotationType.getValueType()
      • getValues

        public <T> List<T> getValues​(Unit unit)
                              throws BaseException
        Get the values for this annotation in a specific unit. The values are of a Type appropriate for the given annotation type, ie. Integer object for an integer annotation type. All objects in the list are of the same type.
        Parameters:
        unit - The unit to convert the values to, or null to get the values in the unit used on this annotation
        Returns:
        A list of objects
        Throws:
        BaseException - If there is an error
        Since:
        2.9
        See Also:
        AnnotationType.getValueType()
      • getValuesVersion

        public int getValuesVersion()
        Get the version number of the item keeping the values. This is useful when you need to know if the annotation values has been modified by another transaction since they were read from the database. Unlike other items the version number of the annotation item doesn't change when the values are modified.
        Returns:
        The version number as an int.
      • setValueIfDifferent

        public boolean setValueIfDifferent​(Object value,
                                           Unit unit)
                                    throws PermissionDeniedException,
                                           InvalidDataException,
                                           BaseException
        Set the value of the annotation, replacing any previous values if they are different. No change is made if the new value is the same as the existing value.

        If this annotation type uses project-specific annotations this method behaves differently. If a project is active and this annotation is the default annotation, this method will not update the values. Instead it will load the existing project-specific annotation or create a new one and update that instead (but only if the values are different). Thus, this method may return TRUE even if the valuse in this annotation hasn't changed. The project-specific annotation can be retrieved by calling AnnotationSet.getAnnotation(AnnotationType).

        Parameters:
        value - The new value
        unit - The unit of the value, or null to use the default unit of the annotation type
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission for the annotation or read permission for the annotation type
        InvalidDataException - If the value isn't a valid value for the annotation type, see AnnotationType.validateAnnotationValue(Object)
        BaseException - If there is another error
        Since:
        3.8
      • setValuesIfDifferent

        public boolean setValuesIfDifferent​(List<?> values,
                                            Unit unit)
                                     throws PermissionDeniedException,
                                            InvalidDataException,
                                            BaseException
        Set the values of the annotation, replacing any previous values if they are different. No change is made if the new list of values is the same as the existing values.

        If this annotation type uses project-specific annotations this method behaves differently. If a project is active and this annotation is the default annotation, this method will not update the values. Instead it will load the existing project-specific annotation or create a new one and update that instead (but only if the values are different). Thus, this method may return TRUE even if the valuse in this annotation hasn't changed. The project-specific annotation can be retrieved by calling AnnotationSet.getAnnotation(AnnotationType).

        An exception to the above (since BASE 3.11) is if the annotation was loaded with AnnotationSet.getProjectAnnotation(AnnotationType, Project) in which case currently active project is ignored and the values are always changed on this annotation (eg. the same as if this annotation was not using project-specific annotations). Use the isIgnoringActiveProject() to find out if the active project is ignored or not.

        Parameters:
        values - A list containing the new values
        unit - The unit of the value, or null to use the default unit of the annotation type
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission for the annotation or read permission for the annotation type
        InvalidDataException - If the number of values are too many according to the AnnotationType.getMultiplicity() setting any of the values isn't a valid value for the annotation type, see AnnotationType.validateAnnotationValue(Object)
        BaseException - If there is another error
        Since:
        3.8
      • checkIfDifferent

        public boolean checkIfDifferent​(List<?> values,
                                        Unit unit)
        Check if the given values are different from the values already stored in this annotation.
        Since:
        3.11
      • resyncCloned

        public void resyncCloned()
        If this is a cloned annotation, resync the cloned values. This method does nothing on PRIMARY or INHERITED annotations.
        Since:
        3.6