2.10.0: 2009-02-24

net.sf.basedb.core
Class AnnotationSet

java.lang.Object
  extended by net.sf.basedb.core.BasicItem<AnnotationSetData>
      extended by net.sf.basedb.core.AnnotationSet
All Implemented Interfaces:
AccessControlled, Identifiable

public class AnnotationSet
extends BasicItem<AnnotationSetData>

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: 2008-11-07 09:36:37 +0100 (Fri, 07 Nov 2008) $

Nested Class Summary
private static class AnnotationSet.QueryRuntimeFilterImpl
           
 
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.
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)
          Automatically inherit all annotations of the specified annotation type from parent items unless this annotation set already contains an annotation of the specified type.
 void copyFrom(Annotatable item, boolean overwrite)
          Copy annotations from another annotatable item to this 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.
 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 isUsed()
          Always return TRUE.
 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.
 
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, 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.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.

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

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

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>

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

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.

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

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

2.10.0: 2009-02-24