Package net.sf.basedb.core

Class Annotation

java.lang.Object
net.sf.basedb.core.BasicItem
net.sf.basedb.core.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: 2022-07-29 15:43:11 +0200 (Fri, 29 Jul 2022) $

  • Field Details

    • TYPE

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

    • annotationSet

      private AnnotationSet annotationSet

    • disableATPermissionCheck

      private boolean disableATPermissionCheck

    • ignoreActiveProject

      private boolean ignoreActiveProject

  • Constructor Details

  • Method Details

    • getNewPrimary

      static Annotation getNewPrimary(DbControl dc, AnnotationSet annotationSet, AnnotationTypeData annotationType) throws BaseException
      Create a new primary annotation.
      Parameters:
      dc - The DbControl object
      annotationType - The annotation type of the new annotation
      annotationSet - The annotation set of the new annotation
      Throws:
      BaseException
      Since:
      3.6
      See Also:

    • getNewInherited

      static Annotation getNewInherited(DbControl dc, AnnotationSet annotationSet, AnnotationData inheritedFrom, boolean clone) throws BaseException
      Create a new inherited or cloned annotation.
      Parameters:
      dc - The DbControl object
      inheritedFrom - The annotation to inherit
      annotationSet - The annotation set of the new annotation
      clone - If the annotation values should be cloned or not
      Throws:
      BaseException
      Since:
      3.6
      See Also:

    • getById

      public static Annotation getById(DbControl dc, int id) throws ItemNotFoundException, PermissionDeniedException, BaseException
      Get an Annotation 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 Annotation 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

    • getById

      public static Annotation getById(DbControl dc, int id, boolean ignoreActiveProject) throws ItemNotFoundException, PermissionDeniedException, BaseException
      Get an Annotation item when you know the id and ignore the rules for project-specific annotations when modifying the values.
      Throws:
      ItemNotFoundException
      PermissionDeniedException
      BaseException
      Since:
      3.19.4
      See Also:

    • 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

    • getData

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

    • onAfterInsert

      void onAfterInsert() throws BaseException
      Description copied from class: BasicItem
      This method is called on all items directly after Hibernate has inserted it into the database. This method can be used in place of the BasicItem.onBeforeCommit(Transactional.Action) in case the id is needed. The id has not been generated when the onBeforeCommit is called.
      Overrides:
      onAfterInsert in class BasicItem
      Throws:
      BaseException - If there is an error
      See Also:

    • onBeforeCommit

      void onBeforeCommit(Transactional.Action action) throws BaseException
      Nullify links to this annotation from cloned annotations when this annotation is deleted (since the cloned annotation should not be deleted).
      Overrides:
      onBeforeCommit in class BasicItem
      Throws:
      BaseException - If there is an error
      See Also:

    • getPluginPermissions

      PluginPermission getPluginPermissions()
      Overrides:
      getPluginPermissions in class BasicItem

    • 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

    • getAnnotationSet

      public AnnotationSet getAnnotationSet() throws PermissionDeniedException, BaseException
      Get the annotation set this annotation belongs to.
      Returns:
      An AnnotationSet
      Throws:
      PermissionDeniedException - If the logged in user doesn't have read permission for the annotation set (should never happen)
      BaseException - If anything else goes wrong when getting the annotation set.

    • 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

    • getAnnotationType

      public AnnotationType getAnnotationType() throws PermissionDeniedException, BaseException
      Get the annotation type of this annotation.
      Returns:
      An AnnotationType
      Throws:
      PermissionDeniedException - If the logged in user doesn't have read permission for the annotation type
      BaseException - If anything else goes wrong when getting the annotation type.

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

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

    • 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(Object value, Unit unit) throws PermissionDeniedException, InvalidDataException, BaseException
      Check if the given value is different from the values already stored in this annotation.
      Throws:
      PermissionDeniedException
      InvalidDataException
      BaseException
      Since:
      3.11

    • 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

    • convertValues

      private List<Object> convertValues(AnnotationType annotationType, List<?> values, Unit unit)

    • 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