Class Annotation
- All Implemented Interfaces:
AccessControlled
,Identifiable
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) $
-
Nested Class Summary
Modifier and TypeClassDescription(package private) static class
static enum
The annotation source. -
Field Summary
Modifier and TypeFieldDescriptionprivate AnnotationSet
private boolean
private boolean
static final Item
The type of item represented by this class. -
Constructor Summary
ConstructorDescriptionAnnotation
(AnnotationData annotationData) Annotation
(AnnotationData annotationData, AnnotationSet annotationSet) -
Method Summary
Modifier and TypeMethodDescriptionboolean
Check if this annotation belongs to the primaray annotations for a specified annotation set.boolean
checkIfDifferent
(Object value, Unit unit) Check if the given value is different from the values already stored in this annotation.boolean
checkIfDifferent
(List<?> values, Unit unit) Check if the given values are different from the values already stored in this annotation.convertValues
(AnnotationType annotationType, List<?> values, Unit unit) (package private) void
Get the annotation set this annotation belongs to.Get the annotation type of this annotation.static Annotation
Get anAnnotation
item when you know the id.static Annotation
Get anAnnotation
item when you know the id and ignore the rules for project-specific annotations when modifying the values.(package private) AnnotationData
getData()
Get theBasicData
object that holds all data for this item.Get the default annotation that this project-specific annotation is overriding.Get the parent annotation if this is an inherited or cloned annotation.Get the date and time the values in this annotation was last updated.(package private) static Annotation
getNewInherited
(DbControl dc, AnnotationSet annotationSet, AnnotationData inheritedFrom, boolean clone) Create a new inherited or cloned annotation.(package private) static Annotation
getNewPrimary
(DbControl dc, AnnotationSet annotationSet, AnnotationTypeData annotationType) Create a new primary annotation.(package private) PluginPermission
Get the project that this project-specific annotation belongs to.int
Get the ID of the project that this project-specicif annotation belongs to.(package private) static ItemQuery<Annotation>
getQuery()
Get a query configured to retrieve annotations.Get the annotation source.getType()
Get the type of item represented by the object.getUnit()
Get the unit used for the values in this annotation.getUnitConverter
(Unit unit) Get a converter for converting the values in this annotation to a specific unit.<T> Formatter<T>
getUnitFormatter
(Formatter<T> parent, Unit unit) Wrap a parent formatter with a formatter for units.getUnitSymbol
(Unit unit) Shortcut forUnit.getDisplaySymbol()
, but also checks the default unit of the annotation type.<T> List<T>
Get the values this annotation contains.<T> List<T>
Get the values for this annotation in a specific unit.int
Get the version number of the item keeping the values.Get the value type for this annotation type.boolean
hasUnit()
Checks if the values in this annotation has a unit.(package private) void
initPermissions
(int granted, int denied) READ permission is granted if the logged in user has READ permission on the associated item and annotation type.boolean
Checks if this annotation is ignoring the currently active project.boolean
Is this (project-specific) annotation overriding a default value?boolean
Is this annotation a project-specific annotation?(package private) void
This method is called on all items directly after Hibernate has inserted it into the database.(package private) void
onBeforeCommit
(Transactional.Action action) Nullify links to this annotation from cloned annotations when this annotation is deleted (since the cloned annotation should not be deleted).void
If this is a cloned annotation, resync the cloned values.(package private) void
setProjectId
(int projectId) Set the project that this annotation value should belong to.boolean
setValueIfDifferent
(Object value, Unit unit) Set the value of the annotation, replacing any previous values if they are different.boolean
setValuesIfDifferent
(List<?> values, Unit unit) Set the values of the annotation, replacing any previous values if they are different.Methods inherited from class net.sf.basedb.core.BasicItem
addAnnotatableParents, addUsingItems, addUsingItems, breakCircularReferences, checkBatchAnnotatableUsage, checkPermission, equals, getBasicData, getDbControl, getId, getPermissions, getSessionControl, getUsingItems, getVersion, hashCode, hasPermission, isDetached, isInDatabase, isUsed, onAfterCommit, onRollback, setDbControl, setProjectDefaults, toString, validate
-
Field Details
-
TYPE
The type of item represented by this class.- See Also:
-
annotationSet
-
disableATPermissionCheck
private boolean disableATPermissionCheck -
ignoreActiveProject
private boolean ignoreActiveProject
-
-
Constructor Details
-
Annotation
Annotation(AnnotationData annotationData) -
Annotation
Annotation(AnnotationData annotationData, AnnotationSet annotationSet)
-
-
Method Details
-
getNewPrimary
static Annotation getNewPrimary(DbControl dc, AnnotationSet annotationSet, AnnotationTypeData annotationType) throws BaseException Create a new primary annotation.- Parameters:
dc
- The DbControl objectannotationType
- The annotation type of the new annotationannotationSet
- 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 objectinheritedFrom
- The annotation to inheritannotationSet
- The annotation set of the new annotationclone
- 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 anAnnotation
item when you know the id.- Parameters:
dc
- TheDbControl
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 foundPermissionDeniedException
- If the logged in user doesn't have read permission to the itemBaseException
- If there is another error
-
getById
public static Annotation getById(DbControl dc, int id, boolean ignoreActiveProject) throws ItemNotFoundException, PermissionDeniedException, BaseException Get anAnnotation
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
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 theBasicData
object that holds all data for this 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 theItem
enumeration.- Returns:
- A value indicating the type of item
-
initPermissions
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 classBasicItem
- Parameters:
granted
- Permissions that have been granted by the subclassdenied
- Permissions that have been denied by the subclass- Throws:
BaseException
- If the permissions couldn't be initialised
-
onAfterInsert
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 theBasicItem.onBeforeCommit(Transactional.Action)
in case the id is needed. The id has not been generated when theonBeforeCommit
is called.- Overrides:
onAfterInsert
in classBasicItem
- Throws:
BaseException
- If there is an error- See Also:
-
onBeforeCommit
Nullify links to this annotation from cloned annotations when this annotation is deleted (since the cloned annotation should not be deleted).- Overrides:
onBeforeCommit
in classBasicItem
- Throws:
BaseException
- If there is an error- See Also:
-
getPluginPermissions
PluginPermission getPluginPermissions()- Overrides:
getPluginPermissions
in classBasicItem
-
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
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
Get the date and time the values in this annotation was last updated.- Since:
- 2.14
-
belongsTo
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
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 typeBaseException
- If anything else goes wrong when getting the annotation type.
-
getSource
Get the annotation source.- Since:
- 3.6
-
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 thesetValuesIfDifferent(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
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
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
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
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 bygetUnit()
- 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
Wrap a parent formatter with a formatter for units. NOTE! Values should be retrived with the same unit usinggetValues(Unit)
to be correctly formatted with the returned formatter.- Parameters:
parent
- The parent formatter, which should be of the correct type for the annotation valuesunit
- The unit to use for formatting, or null to use the annotation's unit- Returns:
- A formatter object
- Since:
- 2.9
-
getUnitSymbol
Shortcut forUnit.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
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
Get the values this annotation contains. The values are of aType
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()
). UsegetValues(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
Get the values for this annotation in a specific unit. The values are of aType
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 valueunit
- 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 typeInvalidDataException
- If the value isn't a valid value for the annotation type, seeAnnotationType.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 theisIgnoringActiveProject()
to find out if the active project is ignored or not.- Parameters:
values
- A list containing the new valuesunit
- 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 typeInvalidDataException
- If the number of values are too many according to theAnnotationType.getMultiplicity()
setting any of the values isn't a valid value for the annotation type, seeAnnotationType.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
Check if the given values are different from the values already stored in this annotation.- Since:
- 3.11
-
convertValues
-
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
-