net.sf.basedb.core
Class AnnotationSet

java.lang.Object
  net.sf.basedb.core.BasicItem<AnnotationSetData>
      net.sf.basedb.core.AnnotationSet

All Implemented Interfaces:

AccessControlled, Controlled, Identifiable, Transactional

public class AnnotationSet
extends BasicItem<AnnotationSetData>
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: 2010-04-20 10:02:16 +0200 (Tue, 20 Apr 2010) $

Nested Class Summary

private static class

AnnotationSet.QueryRuntimeFilterImpl

Nested classes/interfaces inherited from interface net.sf.basedb.core.Transactional

Transactional.Action

Field Summary

private Annotatable	item The item this annotation set belongs to.
private static QueryRuntimeFilter	RUNTIME_FILTER This filter gives everybody read permission to annotations.
private boolean	snapshotIsInvalid Flag to indicate if this annotation set has been modified and the snapshot must be removed.
static Item	TYPE The type of item represented by this class.

Constructor Summary

AnnotationSet(AnnotationSetData annotationSetData)
Regular constructor if the item is not known beforehand.

AnnotationSet(AnnotationSetData annotationSetData, Annotatable item)
Special constructor to avoid getItem() to hit the database when the item is known beforehand.

Method Summary

int	autoInherit(DbControl dc, AnnotationType annotationType, boolean preferAnnotationSet) Deprecated. In 2.15, use autoInherit(DbControl, Collection, SnapshotManager, boolean) instead since it has better performance
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.
void	copyFrom(Annotatable item, boolean overwrite) Copy annotations from another annotatable item to this annotation set.
static AnnotationSetSnapshot	createSnapshot(DbControl dc, int annotationSetId) Create a new annotation snapshot for the given annotation set.
Annotation	findAnnotation(AnnotationType annotationType) Deprecated. Use findAnnotations(DbControl, AnnotationType, Boolean) instead
List<Annotation>	findAnnotations(DbControl dc, AnnotationType annotationType, Boolean findInherited) Find annotations of the specified annotation type among all annotations including the inherited annotations.
ItemQuery<Annotation>	getAllInheritedAnnotations() Get a query that returns all inherited (directly and indirectly) annotations in this annotation set.
Annotation	getAnnotation(AnnotationType annotationType) Get the Annotation object of the specified annotation type.
ItemQuery<Annotation>	getAnnotations() Get a query that reurns all primary annotations in this annotation set.
static AnnotationSet	getById(DbControl dc, int id) Get an AnnotationSet item when you know the id.
ItemQuery<Annotation>	getInheritedAnnotations() Get a query that returns directly inherited annotations in this annotation set.
ItemQuery<AnnotationSet>	getInheritedAnnotationSets() Get a query that returns all inherited annotation sets in this annotation set.
ItemQuery<AnnotationSet>	getInheritingAnnotationSets() Get a query that returns all annotation sets inheriting from this annotation set.
Annotatable	getItem() Get the item this annotation set belongs to.
Annotatable	getItem(DbControl dc) Get the item this annotation set belongs to using a specific DbControl for database access.
int	getItemId() Get the ID of the item this annotation set belongs to.
Item	getItemType() Get the Item type of the item this annotation set belongs to.
(package private) static AnnotationSet	getNew(DbControl dc, Annotatable item) Create a new annotation set for the specified item.
(package private) PluginPermission	getPluginPermissions()
(package private) static ItemQuery<AnnotationSet>	getQuery() Get a ItemQuery object configured to retrieve AnnotationSet items.
Item	getType() Get the type of item represented by the object.
Set<ItemProxy>	getUsingItems() Get the item this annotation set belongs to.
boolean	hasAnnotation(AnnotationType annotationType) Check if the annotation set contains an annotation of the specified type.
void	inheritAnnotation(Annotation annotation) Inherit an annotation.
void	inheritAnnotationSet(AnnotationSet annotationSet) Inherit an annotation set.
(package private) void	initPermissions(int granted, int denied) READ permission is granted to all users.
boolean	isInherited(Annotation annotation) Check if an annotation is inherited or not by this annotation set.
boolean	isInherited(AnnotationSet annotationSet) Check if an annotation set is inherited or not by this annotation set.
boolean	isSnapshotInvalid() Get the status of the 'invalid snapshot' flag.
boolean	isUsed() Always return TRUE.
(package private) static int	loadItemId(org.hibernate.Session session, Item itemType, int annotationSetId) Load the id of the item that this annotation set belongs to.
(package private) void	onBeforeCommit(Transactional.Action action) Remove the cached snapshot if needed.
void	removeAnnotation(AnnotationType annotationType) Delete the annotation of the specified annotation type.
void	removeInheritedAnnotation(Annotation annotation) Remove an inherited an annotation.
void	removeInheritedAnnotationSet(AnnotationSet annotationSet) Remove an inherited an annotation set.
(package private) void	setItem(Annotatable item) Set the item this annotation set belongs to.
void	setSnapshotInvalid() Mark the snapshot (if it exists) of this annotation set as invalid.

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

addUsingItems, addUsingItems, checkPermission, equals, getData, getDbControl, getId, getPermissions, getSessionControl, getVersion, hashCode, hasPermission, isDetached, isInDatabase, onAfterCommit, onAfterInsert, 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.ANNOTATIONSET, getType()

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 Detail

AnnotationSet

AnnotationSet(AnnotationSetData annotationSetData)

Regular constructor if the item is not known beforehand.

AnnotationSet

AnnotationSet(AnnotationSetData annotationSetData,
              Annotatable item)

Special constructor to avoid getItem() to hit the database when the item is known beforehand.

See Also:

AnnotatedItem.getAnnotationSet()

Method Detail

getNew

static AnnotationSet getNew(DbControl dc,
                            Annotatable item)
                     throws BaseException

Create a new annotation set for the specified item.

Throws:

BaseException

See Also:

AnnotatedItem.getAnnotationSet()

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(org.hibernate.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

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

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()

getUsingItems

public Set<ItemProxy> getUsingItems()
                             throws BaseException

Get the item this annotation set belongs to.

Overrides:

getUsingItems in class BasicItem<AnnotationSetData>

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:

BasicItem.addUsingItems(Set, Item, org.hibernate.Query)

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 WRITE permission on the associated item.

Overrides:

initPermissions in class BasicItem<AnnotationSetData>

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

onBeforeCommit

void onBeforeCommit(Transactional.Action action)
              throws BaseException

Remove the cached snapshot if needed.

Overrides:

onBeforeCommit in class BasicItem<AnnotationSetData>

Throws:

BaseException - If there is an error

See Also:

Transactional, Core API overview - Transaction handling, Coding rules and guidelines for item classes

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) method.

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

See Also:

findAnnotations(DbControl, AnnotationType, Boolean)

hasAnnotation

public boolean hasAnnotation(AnnotationType annotationType)

Check if the annotation set contains an annotation of the specified type.

Parameters:

annotationType - An AnnotationType object

Returns:

TRUE if the annotation set contains an annotation of the specified type, FALSE otherwise

findAnnotation

public Annotation findAnnotation(AnnotationType annotationType)
                          throws PermissionDeniedException

Deprecated. Use findAnnotations(DbControl, AnnotationType, Boolean) instead

Find an annotation of the specified annotation type among all annotations including the inherited annotations. This method will first search for the annotation in the following order:

1. The primary annotations
2. The inherited annotations
3. The inherited annotation sets

If no annotation of the specified type is found, null is returned. If more than one annotation of the specified type exists only the first one found is returned.

Parameters:

annotationType - The annotation type to look for

Returns:

An Annotation object or null

Throws:

PermissionDeniedException

findAnnotations

public List<Annotation> findAnnotations(DbControl dc,
                                        AnnotationType annotationType,
                                        Boolean findInherited)
                                 throws PermissionDeniedException

Find annotations of the specified annotation type among all annotations including the inherited annotations. This method will search for annotations in the following order:

1. The primary annotations
2. The inherited annotations
3. The inherited annotation sets

If no annotation of the specified type is found, an empty list is returned.

Note! This method only looks in the database. Changes that have been made in the current transaction and not yet committed to the database are not included in the result.

NOTE!!!! Do not use this method if you need to find many annotation in many items. It has bad performance. It is better to use the cached snapshots. See SnapshotManager.

Parameters:

dc - The DbControl to use for database access

annotationType - The annotation type to look for

findInherited - TRUE if the method always should try to find inherited annotations, FALSE if it never should try, or null if it only should try if it hasn't found any annotation so far

Returns:

A list Annotation objects (may be empty)

Throws:

PermissionDeniedException - If the logged in user don't have the proper permissions to access the database.

Since:

2.5

removeAnnotation

public void removeAnnotation(AnnotationType annotationType)
                      throws PermissionDeniedException,
                             InvalidDataException,
                             BaseException

Delete the annotation of the specified annotation type.

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

getAnnotations

public ItemQuery<Annotation> getAnnotations()

Get a query that reurns all primary annotations in this annotation set.

Returns:

An ItemQuery object

inheritAnnotation

public void inheritAnnotation(Annotation annotation)
                       throws PermissionDeniedException,
                              InvalidDataException

Inherit an annotation.

Parameters:

annotation - The annotation to inherit

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission for this annotation set or use permission for the annotation

InvalidDataException - If the annotation is null

removeInheritedAnnotation

public void removeInheritedAnnotation(Annotation annotation)
                               throws PermissionDeniedException,
                                      InvalidDataException

Remove an inherited an annotation.

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

getInheritedAnnotations

public ItemQuery<Annotation> getInheritedAnnotations()
                                              throws BaseException

Get a query that returns directly inherited annotations in this annotation set. Directly inherited annotations are annotations that are linked to this annotation set.

Returns:

An ItemQuery object

Throws:

BaseException - If getting the query fails.

See Also:

inheritAnnotation(Annotation)

getAllInheritedAnnotations

public ItemQuery<Annotation> getAllInheritedAnnotations()

Get a query that returns all inherited (directly and indirectly) annotations in this annotation set. The directy inherited annotations include annotations added by inheritAnnotation(Annotation), the indirectly inherited annotations include annotations in annotation sets added by inheritAnnotationSet(AnnotationSet)

Returns:

An ItemQuery object

See Also:

getInheritedAnnotations()

inheritAnnotationSet

public void inheritAnnotationSet(AnnotationSet annotationSet)
                          throws PermissionDeniedException,
                                 InvalidDataException

Inherit an annotation set.

Parameters:

annotationSet - The annotation set to inherit

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

removeInheritedAnnotationSet

public void removeInheritedAnnotationSet(AnnotationSet annotationSet)
                                  throws PermissionDeniedException,
                                         InvalidDataException

Remove an inherited an annotation set.

Parameters:

annotationSet - The annotation set to remove

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission for this annotation set

InvalidDataException - If the annotation set is null

isInherited

public boolean isInherited(AnnotationSet annotationSet)
                    throws InvalidDataException

Check if an annotation set is inherited or not by this annotation set.

Parameters:

annotationSet - The annotation set to check

Returns:

TRUE if inherited, FALSE otherwise.

Throws:

InvalidDataException - If the annotation set is null

getInheritedAnnotationSets

public ItemQuery<AnnotationSet> getInheritedAnnotationSets()

Get a query that returns all inherited annotation sets in this annotation set.

Returns:

An ItemQuery object

Throws:

BaseException - If there is an error

autoInherit

public int autoInherit(DbControl dc,
                       AnnotationType annotationType,
                       boolean preferAnnotationSet)

Deprecated. In 2.15, use autoInherit(DbControl, Collection, SnapshotManager, boolean) instead since it has better performance

Automatically inherit all annotations of the specified annotation type from parent items unless this annotation set already contains an annotation of the specified type.

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

annotationType - The annotation type to look for

preferAnnotationSet - If TRUE, the entire annotation set containing the found annotation is inherited, otherwise only the found annotation is inherited

Since:

2.9

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

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

Parameters:

item - The item to copy annotation from

overwrite - TRUE to overwrite existing values

Since:

2.5

getInheritingAnnotationSets

public ItemQuery<AnnotationSet> getInheritingAnnotationSets()

Get a query that returns all annotation sets inheriting from this annotation set.

Returns:

An ItemQuery object

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