net.sf.basedb.core
Class BasicItem<D extends BasicData>

java.lang.Object
  net.sf.basedb.core.BasicItem<D>

All Implemented Interfaces:

AccessControlled, Identifiable

Direct Known Subclasses:

Annotation, AnnotationSet, AnyToAny, BasicChildItem, BioPlateEventType, BioPlateType, ChangeHistory, ChildItem, DataFileType, DiskUsage, ExtraValueType, FileSet, FileSetMember, FileType, Group, HardwareType, Key, Message, MimeType, News, OwnedItem, PlateGeometry, Platform, PluginType, ProtocolType, Quantity, Quota, QuotaType, ReporterType, Role, Session, Setting, SoftwareType, Unit, User

public abstract class BasicItem<D extends BasicData>
extends Object
implements Identifiable

This is the root superclass of all item classes. All items must inherit from this class. This class provides access to the id, type and version of the item as well as permission checking methods.

Version:

2.0

Author:

Nicklas

Last modified

$Date: 2010-08-13 10:50:27 +0200 (Fri, 13 Aug 2010) $

Field Summary

private D	data The data class from the net.sf.basedb.core.data layer that holds the data for this item.
private WeakReference<DbControl>	dc A reference to the current DbControl object.
private int	permissions The logged in user's permission to this item.

Constructor Summary

BasicItem(D data)
Create a new instance.

Method Summary

protected void	addUsingItems(Set<ItemProxy> using, Item itemType, org.hibernate.Query query) Add items to the set of items using this one.
protected void	addUsingItems(Set<ItemProxy> using, org.hibernate.Query query) Add items to the set of items using this one.
void	checkPermission(Permission permission) Checks if the logged in user has the specified permission on this item.
boolean	equals(Object o) Check if this item is equal to another item.
(package private) D	getData() Get the BasicData object that holds all data for this item.
DbControl	getDbControl() Get the DbControl object that currently manages this item.
int	getId() Get the id for the item.
Set<Permission>	getPermissions() Get the logged in user's permissions on the item.
(package private) PluginPermission	getPluginPermissions()
SessionControl	getSessionControl() Get the SessionControl object that manages this item.
Set<ItemProxy>	getUsingItems() Get all items that are using this item.
int	getVersion() Get the version number of the item.
int	hashCode() The hash code is calculated at object construction and remains the same during the objects lifetime.
boolean	hasPermission(Permission permission) Checks if the logged in user has the specified permission on this item.
(package private) void	initPermissions(int granted, int denied) Initialise the logged in user's permissions for this item.
boolean	isDetached() Check if this item is attached to a DbControl object or not.
boolean	isInDatabase() Checks if the item has been saved to the database or not.
boolean	isUsed() Check if this item is used by some other item.
(package private) void	onAfterCommit(Transactional.Action action) This method is called on each Transactional object after a successful commit to the database.
(package private) void	onAfterInsert() This method is called on all items directly after Hibernate has inserted it into the database.
(package private) void	onBeforeCommit(Transactional.Action action) This method is called on each Transactional item and on all items if the action is Transactional.Action.CREATE or Transactional.Action.DELETE before a commit is issued to the database.
(package private) void	onRollback(Transactional.Action action) This method is called on each Transactional object after an unsuccessful commit to the database.
(package private) void	setDbControl(DbControl dbControl) Set the DbControl object that should manage this item.
(package private) void	setProjectDefaults(Project activeProject) This method is called before inserting new items into the database to allow items to propagate default values from the active project.
String	toString()
(package private) BasicItemInfo	toTransferable(BasicItemInfo info)
(package private) void	validate() This method is called on each Validatable item before is saved to the database.

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.basedb.core.Identifiable

getType

Field Detail

data

private final D extends BasicData data

The data class from the net.sf.basedb.core.data layer that holds the data for this item.

dc

private WeakReference<DbControl> dc

A reference to the current DbControl object. We use a WeakReference since we it is always the client applications responsibility to keep control over the DbControl object.

permissions

private int permissions

The logged in user's permission to this item. Calculated by the initPermissions(int, int) method.

Constructor Detail

BasicItem

BasicItem(D data)

Create a new instance. Do not call this directly. Use the DbControl.newItem(Class, Object[]) or DbControl.getItem(Class, BasicData, Object[]) methods instead.

Method Detail

hasPermission

public final boolean hasPermission(Permission permission)

Checks if the logged in user has the specified permission on this item. The default implementation only checks the role keys for permissions. A subclass may not override this method since it would make it possible to bypass security checks.

Subclasses that needs to check other keys, such as the SharedItem should override the initPermissions(int,int) method instead.

Specified by:

hasPermission in interface AccessControlled

Parameters:

permission - A value from the Permission class

Returns:

TRUE if the user has the permission, FALSE otherwise

checkPermission

public final void checkPermission(Permission permission)
                           throws PermissionDeniedException

Checks if the logged in user has the specified permission on this item. If not, a PermissionDeniedException is thrown.

Specified by:

checkPermission in interface AccessControlled

Parameters:

permission - A value from the Permission class

Throws:

PermissionDeniedException - If the logged in user doesn't have the requested permission

getPermissions

public final Set<Permission> getPermissions()

Description copied from interface: AccessControlled

Get the logged in user's permissions on the item.

Specified by:

getPermissions in interface AccessControlled

getId

public final int getId()

Description copied from interface: Identifiable

Get the id for the item. If it hasn't yet been saved to the database 0 is returned.

Specified by:

getId in interface Identifiable

Returns:

The id of the item or 0

getVersion

public final int getVersion()

Description copied from interface: Identifiable

Get the version number of the item. The version number is incremented each time the item is updated and is used to prevent that the same item is updated at the same time by two or more different threads or processes.

Specified by:

getVersion in interface Identifiable

toString

public String toString()

Overrides:

toString in class Object

equals

public final boolean equals(Object o)

Check if this item is equal to another item. They are considered to be equal if their BasicData objects are equal.

Overrides:

equals in class Object

See Also:

BasicData.equals(Object)

hashCode

public final int hashCode()

The hash code is calculated at object construction and remains the same during the objects lifetime. For new items the hash code is randomly generated. Items loaded from the database calculates the hash code from the from the id.

Overrides:

hashCode in class Object

See Also:

BasicData.hashCode()

toTransferable

BasicItemInfo toTransferable(BasicItemInfo info)

Since:

2.5

isInDatabase

public final boolean isInDatabase()

Checks if the item has been saved to the database or not.

Returns:

TRUE if the item is saved to the database, FALSE otherwise

isDetached

public final boolean isDetached()

Check if this item is attached to a DbControl object or not. An item is detached if there is no DbControl, if it is closed, or if is not managed by the DbControl.

Returns:

TRUE if the item is detached, FALSE otherwise

See Also:

DbControl.detachItem(BasicItem), DbControl.reattachItem(BasicItem), DbControl.saveItem(BasicItem)

isUsed

public boolean isUsed()
               throws BaseException

Check if this item is used by some other item. With used we mean that another item is linking to this item in way that prevents this item from beeing deleted. Ie. if we tried to delete an item that is used, we would get a foreign key violation error from the database. If the subclass overrides this method it should propagate the call to the superclass, ie. super.isUsed(), unless it has decided that the item is used by some other means.

Returns:

TRUE if this item is used, FALSE otherwise

Throws:

BaseException - If not able to tell if item is used or not.

See Also:

getUsingItems()

getUsingItems

public Set<ItemProxy> getUsingItems()
                             throws BaseException

Get all items that are using this item. This method must be implemented in a way that is consistent with the isUsed() method. Ie. a subclass must override both or none of these methods. The method must return a set with proxies for all items (even if the logged in user doesn't have read permission for all of them). With the proxy it is possible to get the ID and type of the item. To get full access to the item the logged in user must of course have read permission to it.

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:

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

addUsingItems

protected void addUsingItems(Set<ItemProxy> using,
                             Item itemType,
                             org.hibernate.Query query)

Add items to the set of items using this one.

Parameters:

using - The set to add to

itemType - The type of items to add

query - A Hibernate query that returns the ID of items that are using this one

Since:

2.2

addUsingItems

protected void addUsingItems(Set<ItemProxy> using,
                             org.hibernate.Query query)

Add items to the set of items using this one.

Parameters:

using - The set to add to

query - A Hibernate query that returns BasicData objects

Since:

2.2

getData

final D getData()

Get the BasicData object that holds all data for this item.

getDbControl

public final DbControl getDbControl()
                             throws ConnectionClosedException

Get the DbControl object that currently manages this item.

Throws:

ConnectionClosedException - If the item is connected to a closed DbControl object, or not connected at all

setDbControl

final void setDbControl(DbControl dbControl)

Set the DbControl object that should manage this item. A null value detaches the item

getSessionControl

public final SessionControl getSessionControl()
                                       throws ConnectionClosedException

Get the SessionControl object that manages this item.

Throws:

ConnectionClosedException - If the item is not connected to a DbControl object

initPermissions

void initPermissions(int granted,
                     int denied)
               throws BaseException

Initialise the logged in user's permissions for this item. For items loaded from the database, the default implementation checks the role keys. For new items, write permission is added.

Subclasses that needs to check other keys or properties, such as the OwnedItem and SharedItem should override this method. The subclass should calculate additional permissions to be granted or denied, and combine those with whatever was passed as parameters. Use the binary OR operator ( | ) to combine the permissions. Finally the subclass must call super.initPermissions(granted, denied).

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

validate

void validate()
        throws InvalidDataException,
               BaseException

This method is called on each Validatable item before is saved to the database. If the subclass overrides this method it should also propagate the call to the superclass, ie. super.validate().

Throws:

BaseException - If there is an error

InvalidDataException

See Also:

Validatable, Core API overview - Data validation, Coding rules and guidelines for item classes

onBeforeCommit

void onBeforeCommit(Transactional.Action action)
              throws BaseException

This method is called on each Transactional item and on all items if the action is Transactional.Action.CREATE or Transactional.Action.DELETE before a commit is issued to the database. If the subclass overrides this method it must also propagate the call to the superclass, ie. super.onBeforeCommit(action).

Throws:

BaseException - If there is an error

See Also:

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

setProjectDefaults

void setProjectDefaults(Project activeProject)
                  throws BaseException

This method is called before inserting new items into the database to allow items to propagate default values from the active project. This method is only called when a project is active.

Implementation note! Subclasses should only set default values for properties that hasn't been set explicitly by client code, also accounting for setAbc(null) calls.

Parameters:

activeProject - The currently active project

Throws:

BaseException

Since:

2.9

onAfterInsert

void onAfterInsert()
             throws BaseException

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 onBeforeCommit(Transactional.Action) in case the id is needed. The id has not been generated when the onBeforeCommit is called.

Throws:

BaseException - If there is an error

See Also:

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

onAfterCommit

void onAfterCommit(Transactional.Action action)

This method is called on each Transactional object after a successful commit to the database. If the subclass overrides this method it should also propagate the call to the superclass, ie. super.onAfterCommit(action). It is forbidden to access the DbControl object from this method and it must not throw any exceptions. All exceptions should be logged using the Application.getLogger() object.

See Also:

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

onRollback

void onRollback(Transactional.Action action)

This method is called on each Transactional object after an unsuccessful commit to the database. If the subclass overrides this method it should also propagate the call to the superclass, ie. super.onRollback(action). It is forbidden to access the DbControl object from this method and it must not throw any exceptions. All exceptions should be logged using the Application.getLogger() object.

See Also:

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