net.sf.basedb.core
Class Annotation

java.lang.Object
  net.sf.basedb.core.BasicItem<AnnotationData>
      net.sf.basedb.core.Annotation

All Implemented Interfaces:

AccessControlled, Identifiable

public class Annotation
extends BasicItem<AnnotationData>

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: 2009-10-09 10:54:34 +0200 (Fri, 09 Oct 2009) $

Nested Class Summary

private static class

Annotation.QueryRuntimeFilterImpl

Field Summary

private AnnotationSet	annotationSet
private static QueryRuntimeFilter	RUNTIME_FILTER This filter gives everybody read permission to annotations.
static Item	TYPE The type of item represented by this class.

Constructor Summary

Annotation(AnnotationData annotationData)

Annotation(AnnotationData annotationData, AnnotationSet annotationSet)

Method Summary

boolean	belongsTo(AnnotationSet as) Check if this annotation belongs to the primaray annotations for a specified annotation set.
AnnotationSet	getAnnotationSet() Get the annotation set this annotation belongs to.
AnnotationType	getAnnotationType() Get the annotation type of this annotation.
static Annotation	getById(DbControl dc, int id) Get an Annotation item when you know the id.
Date	getLastUpdate() Get the date and time the values in this annotation was last updated.
(package private) static Annotation	getNew(DbControl dc, AnnotationType annotationType, AnnotationSet annotationSet) Create a new annotation.
(package private) PluginPermission	getPluginPermissions()
(package private) static ItemQuery<Annotation>	getQuery() Get a query configured to retrieve annotations.
Item	getType() Get the type of item represented by the object.
Unit	getUnit() Get the unit used for the values in this annotation.
UnitConverter	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.
String	getUnitSymbol(Unit unit) Shortcut for Unit.getDisplaySymbol(), but also checks the default unit of the annotation type.
List<?>	getValues() Get the values this annotation contains.
List<?>	getValues(Unit unit) Get the values for this annotation in a specific unit.
int	getValuesVersion() Get the version number of the item keeping the values.
Type	getValueType() 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.
void	setValue(Object value)
void	setValue(Object value, Unit unit) Set the value of the annotation, replacing any previous values.
void	setValues(List<?> values)
void	setValues(List<?> values, Unit unit) Set the values of the annotation, replacing any previous values.

Methods inherited from class net.sf.basedb.core.BasicItem

addUsingItems, addUsingItems, checkPermission, equals, getData, getDbControl, getId, getPermissions, getSessionControl, getUsingItems, getVersion, hashCode, hasPermission, isDetached, isInDatabase, isUsed, onAfterCommit, onAfterInsert, onBeforeCommit, onRollback, setDbControl, setProjectDefaults, toString, toTransferable, validate

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

TYPE

public static final Item TYPE

The type of item represented by this class.

See Also:

Item.ANNOTATION, getType()

RUNTIME_FILTER

private static final QueryRuntimeFilter RUNTIME_FILTER

This filter gives everybody read permission to annotations.

annotationSet

private AnnotationSet annotationSet

Constructor Detail

Annotation

Annotation(AnnotationData annotationData)

Annotation

Annotation(AnnotationData annotationData,
           AnnotationSet annotationSet)

Method Detail

getNew

static Annotation getNew(DbControl dc,
                         AnnotationType annotationType,
                         AnnotationSet annotationSet)
                  throws BaseException

Create a new annotation.

Parameters:

dc - The DbControl object

annotationType - The annotation type of the new annotation

annotationSet - The annotation set of the new annotation

Throws:

BaseException

See Also:

AnnotationSet.getAnnotation(AnnotationType)

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

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. CREATE, WRITE and DELETE permissions are granted if the logged in user has WRITE permission on the associated item.

Overrides:

initPermissions in class BasicItem<AnnotationData>

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

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.

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 List<?> 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 List<?> 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.

setValue

public void setValue(Object value)
              throws PermissionDeniedException,
                     InvalidDataException,
                     BaseException

Throws:

PermissionDeniedException

InvalidDataException

BaseException

setValue

public void setValue(Object value,
                     Unit unit)
              throws PermissionDeniedException,
                     InvalidDataException,
                     BaseException

Set the value of the annotation, replacing any previous values.

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:

2.9

setValues

public void setValues(List<?> values)
               throws PermissionDeniedException,
                      InvalidDataException,
                      BaseException

Throws:

PermissionDeniedException

InvalidDataException

BaseException

setValues

public void setValues(List<?> values,
                      Unit unit)
               throws PermissionDeniedException,
                      InvalidDataException,
                      BaseException

Set the values of the annotation, replacing any previous values.

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