Package net.sf.basedb.core

Class AnnotationSet

java.lang.Object
net.sf.basedb.core.BasicItem
net.sf.basedb.core.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:
Last modified
$Date: 2019-04-11 09:31:26 +0200 (tors, 11 apr. 2019) $

  • Field Details

    • TYPE

      public static final Item TYPE
      The type of item represented by this class.
      See Also:

    • 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.

  • Constructor Details

  • Method Details

    • getNew

      static AnnotationSet getNew(DbControl dc, Annotatable item) throws BaseException
      Create a new annotation set for the specified item.
      Throws:
      BaseException
      See Also:

    • getById

      public static AnnotationSet getById(DbControl dc, int id) throws ItemNotFoundException, PermissionDeniedException, BaseException
      Get an AnnotationSet item when you know the id.
      Parameters:
      dc - The DbControl which will be used for permission checking and database access.
      id - The id of the item to load
      Returns:
      The AnnotationSet item
      Throws:
      ItemNotFoundException - If an item with the specified id is not found
      PermissionDeniedException - If the logged in user doesn't have read permission to the item
      BaseException - If there is another error

    • 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

    • getData

      AnnotationSetData getData()
      Description copied from class: BasicItem
      Get the BasicData object that holds all data for this item.
      Specified by:
      getData in class BasicItem

    • 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:

    • getUsingItems

      public Set<ItemProxy> getUsingItems() throws BaseException
      Get the item this annotation set belongs to.
      Overrides:
      getUsingItems in class BasicItem
      Returns:
      A set containing proxies for the items, or an empty set if no items are using this item
      Throws:
      BaseException - If there is an error loading the items
      Since:
      2.2
      See Also:

    • 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

    • getPluginPermissions

      PluginPermission getPluginPermissions()
      Overrides:
      getPluginPermissions in class BasicItem

    • onBeforeCommit

      void onBeforeCommit(Transactional.Action action) throws BaseException
      Remove the cached snapshot if needed.
      Overrides:
      onBeforeCommit in class BasicItem
      Throws:
      BaseException - If there is an error
      See Also:

    • getItem

      public Annotatable getItem() throws PermissionDeniedException, BaseException
      Get the item this annotation set belongs to.
      Returns:
      The Annotatable item
      Throws:
      PermissionDeniedException - If the logged in user doesn't have read permission to the item
      BaseException - If there is another error

    • getItem

      public Annotatable getItem(DbControl dc) throws PermissionDeniedException, BaseException
      Get the item this annotation set belongs to using a specific DbControl for database access. If the item has already been loaded it is re-loaded by the given DbControl.
      Parameters:
      dc - An open DbControl, or null to use the current DbControl associated with this annotation set
      Returns:
      The Annotatable item
      Throws:
      PermissionDeniedException
      BaseException
      Since:
      2.9

    • 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.

    • getAnnotation

      public Annotation getAnnotation(AnnotationType annotationType) throws PermissionDeniedException, InvalidDataException, BaseException
      Get the Annotation object of the specified annotation type. If the annotation set doesn't contain an annotation of the specified type a new object is created and automatically saved to the database when DbControl.commit() is called. To check if an annotation of a certain annotation type exists without creating a new annotation use the hasAnnotation(AnnotationType, Annotation.Source) method.

      If the annotation type has enabled project-specific annotations (see AnnotationType.getProjectAnnotations()), this method will return the annotation for the currently enabled project or the default annotation if no specific annotation exists. If a new annotation is created it is assigned to the currently active project.

      Parameters:
      annotationType - The annotation type
      Returns:
      An Annotation object
      Throws:
      PermissionDeniedException - If a new annotation must be created and the logged in user doesn't have write permission
      InvalidDataException - If a new annotation must be created and the annotation type isn't valid for this type of item
      BaseException - If there is another error

    • 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

    • removeAnnotation

      public void removeAnnotation(AnnotationType annotationType) throws PermissionDeniedException, InvalidDataException, BaseException
      Delete the primary annotation of the specified annotation type. If the annotation type has enabled project-specific annotations (see AnnotationType.getProjectAnnotations()), this method will only remove an annotation if it is specific to the currently active project (or the default annotation if no project is active)
      Parameters:
      annotationType - The type of the annotation to delete
      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

    • 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