Class AnnotationSet

  • All Implemented Interfaces:
    AccessControlled, Controlled, Identifiable, Transactional

    public class AnnotationSet
    extends BasicItem
    implements Transactional
    An annotation set is the container for all annotations on an item. An item can have one annotation of each annotation type that is defined for it.

    An item can also inherit annotation from it's parents. It is possible to inherit all annotations or only specific ones. In the first case this means that if the parent gets new annotations those are automatically inherited. In the second case the inherticane is lost if the annotation is deleted. If a new annotation of the same annotation type is creted later, it is NOT automatically inherited again.

    Version:
    2.0
    Author:
    Nicklas
    See Also:
    AnnotationType, Annotation
    Last modified
    $Date: 2019-04-05 13:42:26 +0200 (fre, 05 apr. 2019) $
    • Field Detail

      • RUNTIME_FILTER

        private static final QueryRuntimeFilter RUNTIME_FILTER
        This filter gives everybody read permission to annotations.
      • item

        private Annotatable item
        The item this annotation set belongs to.
      • snapshotIsInvalid

        private boolean snapshotIsInvalid
        Flag to indicate if this annotation set has been modified and the snapshot must be removed.
    • Method Detail

      • getQuery

        static ItemQuery<AnnotationSet> getQuery()
        Get a ItemQuery object configured to retrieve AnnotationSet items. 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
      • loadItemId

        static int loadItemId​(Session session,
                              Item itemType,
                              int annotationSetId)
        Load the id of the item that this annotation set belongs to.
        Since:
        2.14
      • createSnapshot

        public static AnnotationSetSnapshot createSnapshot​(DbControl dc,
                                                           int annotationSetId)
        Create a new annotation snapshot for the given annotation set. NOTE! This method will always create a new snapshot from the database. The snapshot is not saved in the cache.

        It is recommended that snapshots are cached as files in the static cache since they are much quiker to load. Use SnapshotManager.getSnapshot(DbControl, int) is instead of this method.

        Parameters:
        dc - A DbControl to use for database access
        annotationSetId - The ID of the annotation set
        Returns:
        A snapshot, or null if the annotation set with the given id doesn't exist
        Since:
        2.14
      • deleteEmptyAnnotationSets

        public static int deleteEmptyAnnotationSets​(ProgressReporter progress)
                                             throws BaseException
        Delete all empty annotation sets. This method is intended to be executed at regular intervals by a cleanup application and will remove annotation sets that have no primary or inherited annotations.
        Returns:
        The number of deleted annotation sets
        Throws:
        BaseException - If an empty annotation set could not be deleted
        Since:
        3.2
      • deleteEmptyAnnotationSets

        static int deleteEmptyAnnotationSets​(Session session,
                                             ProgressReporter progress)
        Delete all empty annotation sets. This method is intended to be executed at regular intervals by a cleanup application and will remove annotation sets that have no primary or inherited annotations.
        Returns:
        The number of deleted annotation sets
        Throws:
        BaseException - If an empty annotation set could not be deleted
        Since:
        3.2
      • 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
      • isUsed

        public boolean isUsed()
                       throws BaseException
        Always return TRUE. An annotation set always has a one-to-one relation to some item. The annotation set is automatically deleted if that item is deleted.
        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()
      • initPermissions

        void initPermissions​(int granted,
                             int denied)
                      throws BaseException
        READ permission is granted to all users. CREATE, WRITE and DELETE permissions are granted if the logged in user has RESTRICTED_WRITE 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
      • getItemId

        public int getItemId()
        Get the ID of the item this annotation set belongs to. This may need to hit the database unless the id is already known.
        Since:
        2.14
      • setItem

        void setItem​(Annotatable item)
        Set the item this annotation set belongs to.
      • getItemType

        public Item getItemType()
        Get the Item type of the item this annotation set belongs to.
      • getProjectAnnotation

        public Annotation getProjectAnnotation​(AnnotationType annotationType,
                                               Project project)
        Get a value for a project-specific annotation using the specified project instead of the currently active project. Note that this method behaves differently than the getAnnotation(AnnotationType) method. If the annotation type is not using project annotations, the project is ignored If project=null the default annotation value is returned (new or existing) If project!=null a project-specific annotation value is returned (new or existing, the default value is never returned) The returned annotation is always locked to the project it has been defined for. Calling Annotation.setValuesIfDifferent(List, Unit) will always modify the existing value (it will not create a new project-specific value when trying to change the default value).
        Parameters:
        annotationType - The annotation type
        project - A project or null to get the default value
        Since:
        3.11
      • hasAnnotation

        public boolean hasAnnotation​(AnnotationType annotationType,
                                     Annotation.Source source)
        Check if the annotation set contains an annotation of the specified type. If the annotation type has enabled project-specific annotations (see AnnotationType.getProjectAnnotations()), this method will only check if a default annotation or a project-specific annotation for the current project exists. Annotations that are specific for other projects are ignored.
        Parameters:
        annotationType - An AnnotationType object
        source - The source type of the annotation or null if it doesn't matter
        Returns:
        TRUE if the annotation set contains an annotation of the specified type, FALSE otherwise
        Since:
        3.6
      • hasProjectAnnotation

        public boolean hasProjectAnnotation​(AnnotationType annotationType,
                                            Annotation.Source source,
                                            Project project)
        Check if the annotation set contains an annotation of the specified type. If the annotation type has enabled project-specific annotations (see AnnotationType.getProjectAnnotations()), this method will only check if an annotation for the given project exists (or the default value if projectId=0). Annotations that are specific for other projects are ignored.
        Parameters:
        annotationType - An AnnotationType object
        source - The source type of the annotation or null if it doesn't matter
        project - A project or null to check for the default value
        Returns:
        TRUE if the annotation set contains an annotation of the specified type, FALSE otherwise
        Since:
        3.11
      • removeProjectAnnotation

        public void removeProjectAnnotation​(AnnotationType annotationType,
                                            Project project)
                                     throws PermissionDeniedException,
                                            InvalidDataException,
                                            BaseException
        Delete the primary annotation of the specified annotation type. Note that this method is intended to be used with project-specific annotation and will only remove the value for the given project (or the default value if projectId=0).
        Parameters:
        annotationType - The type of the annotation to delete
        project - A project or null to remove the default value
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission
        InvalidDataException - If the annotation type is null
        BaseException - If there is another error
        Since:
        3.11
      • getAnnotations

        public ItemQuery<Annotation> getAnnotations​(Annotation.Source source)
        Get a query returning annotations with the specified source. If the annotation type is using project-specific annotations the query will load project-specific values where they exists and otherwise default values.
        Parameters:
        source - A source or null to not filter on source
      • getProjectAnnotations

        public ItemQuery<Annotation> getProjectAnnotations​(Annotation.Source source,
                                                           Project project)
        Get a query returning annotations with the specified source and belonging to the specified project (or default values if projectId=0).
        Parameters:
        source - A source or null to not filter on source
        project - The project or null to query default values
        Since:
        3.11
      • inheritAnnotation

        public Annotation inheritAnnotation​(Annotation annotation,
                                            boolean clone)
        Inherit or clone an annotation. NOTE! If the annotation is already inherited or cloned, and the clone parameter is not matching, the existing annotations is deleted and replaced with a new annotation.
        Parameters:
        annotation - The annotation to inherit which must be a primary annotation
        clone - TRUE to clone the values, FALSE to only keep the link to the original values
        Returns:
        The new annotation instance (or the old if it already was inherited)
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission for this annotation set or use permission for the annotation or if the annotation type is not enabled for inheritance
        InvalidDataException - If the annotation is null
        Since:
        3.6
      • removeInheritedAnnotation

        public void removeInheritedAnnotation​(Annotation annotation)
                                       throws PermissionDeniedException,
                                              InvalidDataException
        Remove an inherited an annotation. The specified annotation can be either a CLONED or INHERITED annotation in this set or the PRIMARY annotation of another annotation set that is inherited/cloned by this set.
        Parameters:
        annotation - The annotation to remove
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission for this annotation set
        InvalidDataException - If the annotation is null
      • isInherited

        public boolean isInherited​(Annotation annotation)
                            throws InvalidDataException
        Check if an annotation is inherited or not by this annotation set.
        Parameters:
        annotation - The annotation to check
        Returns:
        TRUE if inherited, FALSE otherwise.
        Throws:
        InvalidDataException - If the annotation is null
      • inheritAll

        public int inheritAll​(AnnotationSet annotationSet,
                              boolean clone)
        Utility method for inheriting or cloning all annotations from the given annotation set.
        Parameters:
        annotationSet - The annotation set to inherit
        Returns:
        The number of added annotations
        Throws:
        PermissionDeniedException - If the logged in user doesn't have write permission for this annotation set or use permission for the annotation set to inherit
        InvalidDataException - If the annotation set is null
        Since:
        3.6
      • removeAllInherited

        public int removeAllInherited​(AnnotationSet annotationSet)
        Utility method to stop inheriting all annotations in the given annotation set.
        Returns:
        The number of removed annotations
        Since:
        3.6
      • autoInherit

        public int autoInherit​(DbControl dc,
                               Collection<AnnotationType> annotationTypes,
                               SnapshotManager manager,
                               boolean preferAnnotationSet)
        Automatically inherit all annotations of one or more specified annotation types from parent items that are currntly missing from this annotation set

        This method will only consider parent items that the logged in user has access to with USE permission.

        This method may result in inheriting multiple annotations (from different parent items) of the specified annotation type.

        Parameters:
        dc - The DbControl to use for database access
        annotationTypes - The annotation type to look for
        manager - A snapshot manager that is used to look up annotations
        preferAnnotationSet - If TRUE, the entire annotation set containing the found annotation is inherited, otherwise only the found annotation is inherited NOTE! Since BASE 3.6 this parameter is ignored
        Since:
        2.15
      • copyFrom

        public void copyFrom​(Annotatable item,
                             boolean overwrite)
        Copy annotations from another annotatable item to this annotation set. This method will copy all primary annotations with an annotation type that is valid for this item type. The logged in user doesn't need to have access to all annotation types. The copy will still work. The logged in user must have write permission on this annotation set.

        Project-specific annotations are only copied if they belong to the currently active project.

        Parameters:
        item - The item to copy annotation from
        overwrite - TRUE to overwrite existing values
        Since:
        2.5
      • setSnapshotInvalid

        public void setSnapshotInvalid()
        Mark the snapshot (if it exists) of this annotation set as invalid. The snapshot will be removed when the transaction is committed. Once the snapshot has been marked as invalid it can't be unmarked.
        Since:
        2.14
      • isSnapshotInvalid

        public boolean isSnapshotInvalid()
        Get the status of the 'invalid snapshot' flag.
        Returns:
        TRUE if the snapshot has been marked as invalid, FALSE if not
        Since:
        2.14