3.0.4: 2012-03-05

net.sf.basedb.core
Class BioMaterialEvent

java.lang.Object
  extended by net.sf.basedb.core.BasicItem<D>
      extended by net.sf.basedb.core.ChildItem<BioMaterialEventData>
          extended by net.sf.basedb.core.BioMaterialEvent
All Implemented Interfaces:
AccessControlled, Identifiable, Registered

public class BioMaterialEvent
extends ChildItem<BioMaterialEventData>
implements Registered

This class represents an event in the life of a MeasuredBioMaterial. There are three main types of events: creation events, hybridization events and other events. A creation event is an event that produces a measured biomaterial from other biomaterials. A hybridization event is an event that produces a hybridization from labeled extracts. Other events are used to leave a note about something that affected an already existing biomaterial.

Version:
2.0
Author:
Nicklas
Last modified
$Date: 2012-03-02 15:01:45 +0100 (Fri, 02 Mar 2012) $

Nested Class Summary
static class BioMaterialEvent.Type
          The type of the event.
 
Field Summary
private  boolean hardwareHasBeenSet
           
static int MAX_COMMENT_LENGTH
          The maximum length of the comment about this event.
private  boolean protocolHasBeenSet
           
static Item TYPE
          The type of item represented by this class.
 
Constructor Summary
BioMaterialEvent(BioMaterialEventData bioMaterialEventData)
           
 
Method Summary
private  BioMaterialEventSource addCheckedSource(BioMaterial bioMaterial)
           
 BioMaterialEventSource addSource(BioMaterial bioMaterial)
          Add a biomaterial as a source to this event.
private  void checkAllowedSource(BioMaterial source, boolean forAdd)
          Check if the biomaterial is allowed as a source.
 void clearSources()
          Clear the sources collection and return the used quantities to the source biomaterials.
private  void clearSourcesExcept(BioMaterial parent)
          Clear the sources collection and return the used quantities to the source biomaterials, except for the given biomaterial.
 MeasuredBioMaterial getBioMaterial()
          Get the MeasuredBioMaterial that was affected or created by this event.
 BioPlateEventParticipant getBioPlateEventParticipant()
          Get the bioplate event participant that is the master of this event.
static BioMaterialEvent getById(DbControl dc, int id)
          Get a BioMaterialEvent item when you know the id.
 String getComment()
          Get the comment about this event.
 Date getEntryDate()
          Get the date this event was added to the database.
 Date getEventDate()
          Get the date this event was done in the lab.
 BioMaterialEventSource getEventSource(BioMaterial bioMaterial)
          Get information about a biomaterial used as a source to this event.
 SpecialQuery<BioMaterialEventSource> getEventSources()
          Create a special query that return BioMaterialEventSource objects.
 List<BioMaterialEventSource> getEventSources(DbControl dc, int position)
          Utility method for finding all sources on a given bioassay position.
 BioMaterialEvent.Type getEventType()
          Get the type of event.
 Hardware getHardware()
          Get the Hardware that was used in this event.
static BioMaterialEvent getNew(DbControl dc, MeasuredBioMaterial bioMaterial)
          Create a new BioMaterialEvent of the BioMaterialEvent.Type.OTHER type.
static BioMaterialEvent getNew(DbControl dc, MeasuredBioMaterial bioMaterial, BioPlateEventParticipant master)
          Create a new BioMaterialEvent of the BioMaterialEvent.Type.OTHER type that is linked with a master BioPlateEventParticipant.
(package private) static BioMaterialEvent getNewBioAssayEvent(DbControl dc, PhysicalBioAssay physicalBioAssay, BioPlateEventParticipant master)
          Create a new BioMaterialEvent of the BioMaterialEvent.Type.BIOASSAY type.
(package private) static BioMaterialEvent getNewCreationEvent(DbControl dc, MeasuredBioMaterial bioMaterial, BioPlateEventParticipant master)
          Create a new BioMaterialEvent of the BioMaterialEvent.Type.CREATION type (creation event).
 PhysicalBioAssay getPhysicalBioAssay()
          Get the PhysicalBioAssay that was created by this event.
 Protocol getProtocol()
          Get the Protocol describing the procedure used in this event.
static ItemQuery<BioMaterialEvent> getQuery(MeasuredBioMaterial bioMaterial)
          Get a query that returns events for a biomaterial.
(package private)  SharedData getSharedParent()
          Get the shareable parent item of this child item.
 ItemQuery<? extends BioMaterial> getSources()
          Get a query that return all biomaterials used as sources for this event.
 Item getType()
          Get the type of item represented by the object.
 Float getUsedQuantity()
          Get the quantity that was used from the biomaterial by this event.
 Float getUsedQuantity(MeasuredBioMaterial bioMaterial)
          Get the quantity that was used by this event for the specified biomaterial.
 User getUser()
          Get the User that is responsible for this event.
(package private)  void initPermissions(int granted, int denied)
          READ permission is granted and DELETE permissions is denied to evereyone for creation events.
 boolean isPlateEvent()
          Check if this event is related with a bioplate event.
 boolean isSource(BioMaterial bioMaterial)
          Check if the given biomaterial has been used as a source in this event.
(package private)  void onBeforeCommit(Transactional.Action action)
          Return used guantity to biomaterials on delete action.
 void removeSource(BioMaterial bioMaterial)
          Remove a biomaterial used as a source.
private  void setBioMaterial(MeasuredBioMaterial bioMaterial)
          Set the biomaterial that was affected or created by this event.
 void setComment(String comment)
          Set the comment about this event.
 void setEventDate(Date eventDate)
          Set the date this event was done in the lab.
 void setHardware(Hardware hardware)
          Get the Hardware that was used in this event.
private  void setPhysicalBioAssay(PhysicalBioAssay physicalBioAssay)
          Set the hybidization that was created by this event.
(package private)  void setProjectDefaults(Project activeProject)
          Set protocol and hardware from project default settings.
 void setProtocol(Protocol protocol)
          Set the Protocol that describes the procedure used in this event.
 BioMaterialEventSource setSource(BioMaterial parent)
          Set a single parent item for this event.
 void setUsedQuantity(Float usedQuantity)
          Set the used quantity.
 
Methods inherited from class net.sf.basedb.core.ChildItem
getPermissionForWriteDeleteAndCreate, getPluginPermissions
 
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, onRollback, setDbControl, toString, toTransferable, validate
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface net.sf.basedb.core.Identifiable
getId, getVersion
 
Methods inherited from interface net.sf.basedb.core.AccessControlled
checkPermission, getPermissions, hasPermission
 

Field Detail

TYPE

public static final Item TYPE
The type of item represented by this class.

See Also:
Item.BIOMATERIALEVENT, getType()

protocolHasBeenSet

private boolean protocolHasBeenSet

hardwareHasBeenSet

private boolean hardwareHasBeenSet

MAX_COMMENT_LENGTH

public static final int MAX_COMMENT_LENGTH
The maximum length of the comment about this event. Check the length against this value before calling the setComment(String) method to avoid exceptions.

See Also:
Constant Field Values
Constructor Detail

BioMaterialEvent

BioMaterialEvent(BioMaterialEventData bioMaterialEventData)
Method Detail

getNew

public static BioMaterialEvent getNew(DbControl dc,
                                      MeasuredBioMaterial bioMaterial)
                               throws BaseException
Create a new BioMaterialEvent of the BioMaterialEvent.Type.OTHER type.

Parameters:
dc - The DbControl which will be used for permission checking and database access
bioMaterial - The affected biomaterial
Returns:
The new BioMaterialEvent item
Throws:
BaseException - If there is an error

getNew

public static BioMaterialEvent getNew(DbControl dc,
                                      MeasuredBioMaterial bioMaterial,
                                      BioPlateEventParticipant master)
                               throws BaseException
Create a new BioMaterialEvent of the BioMaterialEvent.Type.OTHER type that is linked with a master BioPlateEventParticipant. If a master bioplate event is used it must be a new event that has not yet been saved to the database.

Parameters:
dc - The DbControl which will be used for permission checking and database access
bioMaterial - The affected biomaterial
master - The master bioplate event or null
Returns:
The new BioMaterialEvent item
Throws:
BaseException - If there is an error
Since:
2.17

getNewCreationEvent

static BioMaterialEvent getNewCreationEvent(DbControl dc,
                                            MeasuredBioMaterial bioMaterial,
                                            BioPlateEventParticipant master)
                                     throws BaseException
Create a new BioMaterialEvent of the BioMaterialEvent.Type.CREATION type (creation event).

Parameters:
dc - The DbControl which will be used for permission checking and database access
bioMaterial - The biomaterial that was created.
master - The master bioplate event or null
Returns:
The new BioMaterialEvent item
Throws:
BaseException - If there is an error
Since:
2.17

getNewBioAssayEvent

static BioMaterialEvent getNewBioAssayEvent(DbControl dc,
                                            PhysicalBioAssay physicalBioAssay,
                                            BioPlateEventParticipant master)
                                     throws BaseException
Create a new BioMaterialEvent of the BioMaterialEvent.Type.BIOASSAY type.

Parameters:
dc - The DbControl which will be used for permission checking and database access
physicalBioAssay - The hybridization that was created.
master - The master bioplate event or null
Returns:
The new BioMaterialEvent item
Throws:
BaseException - If there is an error
Since:
2.17

getById

public static BioMaterialEvent getById(DbControl dc,
                                       int id)
                                throws ItemNotFoundException,
                                       PermissionDeniedException,
                                       BaseException
Get a BioMaterialEvent 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 BioMaterialEvent 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

public static ItemQuery<BioMaterialEvent> getQuery(MeasuredBioMaterial bioMaterial)
                                            throws InvalidDataException
Get a query that returns events for a biomaterial. All events where the given biomaterial is either a source or a product are returned.

Parameters:
bioMaterial - The biomaterial to retreive events for, null is not allowed
Returns:
An ItemQuery object
Throws:
InvalidDataException - If the bioMaterial is null
See Also:
MeasuredBioMaterial.getEvents()

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

onBeforeCommit

void onBeforeCommit(Transactional.Action action)
              throws BaseException
Return used guantity to biomaterials on delete action.

Overrides:
onBeforeCommit in class BasicItem<BioMaterialEventData>
Throws:
BaseException - If there is an error
See Also:
Transactional, Developer documentation: Transactions, Developer documentation: Coding rules and guidelines for item classes

initPermissions

void initPermissions(int granted,
                     int denied)
               throws BaseException
READ permission is granted and DELETE permissions is denied to evereyone for creation events. WRITE permission is denied if this event is associated with a plate event. Other permissions are always checked on the parent biomaterial or hybridization.

Overrides:
initPermissions in class ChildItem<BioMaterialEventData>
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

setProjectDefaults

void setProjectDefaults(Project activeProject)
                  throws BaseException
Set protocol and hardware from project default settings.

Overrides:
setProjectDefaults in class BasicItem<BioMaterialEventData>
Parameters:
activeProject - The currently active project
Throws:
BaseException
Since:
2.9

getSharedParent

SharedData getSharedParent()
Description copied from class: ChildItem
Get the shareable parent item of this child item. This is used by the ChildItem.initPermissions(int, int) method to calculate the logged in user's permissions for the child item.

Specified by:
getSharedParent in class ChildItem<BioMaterialEventData>
Returns:
The parent item

getEventType

public BioMaterialEvent.Type getEventType()
Get the type of event.

See Also:
BioMaterialEvent.Type

getBioMaterial

public MeasuredBioMaterial getBioMaterial()
                                   throws PermissionDeniedException,
                                          BaseException
Get the MeasuredBioMaterial that was affected or created by this event.

Returns:
A MeasuredBioMaterial item or null if this is hybridization event
Throws:
PermissionDeniedException - If the logged in user doesn't have read permission to the biomaterial
BaseException - If there is another error

setBioMaterial

private void setBioMaterial(MeasuredBioMaterial bioMaterial)
                     throws PermissionDeniedException,
                            InvalidDataException
Set the biomaterial that was affected or created by this event.

Throws:
PermissionDeniedException
InvalidDataException

getPhysicalBioAssay

public PhysicalBioAssay getPhysicalBioAssay()
                                     throws PermissionDeniedException,
                                            BaseException
Get the PhysicalBioAssay that was created by this event.

Returns:
A PhysicalBioAssay item or null if this isn't a bioassay event
Throws:
PermissionDeniedException - If the logged in user doesn't have read permission to the bioassay
BaseException - If there is another error

setPhysicalBioAssay

private void setPhysicalBioAssay(PhysicalBioAssay physicalBioAssay)
                          throws PermissionDeniedException,
                                 InvalidDataException
Set the hybidization that was created by this event.

Throws:
PermissionDeniedException
InvalidDataException

isPlateEvent

public boolean isPlateEvent()
Check if this event is related with a bioplate event.

Since:
2.17

getBioPlateEventParticipant

public BioPlateEventParticipant getBioPlateEventParticipant()
Get the bioplate event participant that is the master of this event. If this event has a master event, many properties such as event date, protocol, etc. must be set on the master event.

Returns:
A bioplate event participant or null
Since:
2.17

getUser

public User getUser()
             throws PermissionDeniedException,
                    BaseException
Get the User that is responsible for this event.

Returns:
A User item
Throws:
PermissionDeniedException - If the logged in user doesn't have read permission to the user
BaseException - If there is another error

getProtocol

public Protocol getProtocol()
                     throws PermissionDeniedException,
                            BaseException
Get the Protocol describing the procedure used in this event.

Returns:
A Protocol item, or null if not known
Throws:
PermissionDeniedException - If the logged in user doesn't have read permission to the protocol
BaseException - If there is another error

setProtocol

public void setProtocol(Protocol protocol)
                 throws PermissionDeniedException
Set the Protocol that describes the procedure used in this event.

Parameters:
protocol - A Protocol item, or null if not known
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission on this event or use permission for the protocol

getHardware

public Hardware getHardware()
                     throws PermissionDeniedException,
                            BaseException
Get the Hardware that was used in this event.

Returns:
A Hardware item, or null if not known
Throws:
PermissionDeniedException - If the logged in user doesn't have read permission to the hardware
BaseException - If there is another error

setHardware

public void setHardware(Hardware hardware)
                 throws PermissionDeniedException
Get the Hardware that was used in this event.

Parameters:
hardware - A Hardware item, or null if not known
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission on this event or use permission for the hardware

getUsedQuantity

public Float getUsedQuantity()
Get the quantity that was used from the biomaterial by this event. If this is a creation event this value is the negative value of the original quantity of the created biomaterial.


setUsedQuantity

public void setUsedQuantity(Float usedQuantity)
                     throws PermissionDeniedException
Set the used quantity.

Parameters:
usedQuantity - The quantity to set.
Throws:
PermissionDeniedException - If logged in user doesn't have write permission on current item.

getUsedQuantity

public Float getUsedQuantity(MeasuredBioMaterial bioMaterial)
Get the quantity that was used by this event for the specified biomaterial.

Parameters:
bioMaterial - A biomaterial object

getEventSource

public BioMaterialEventSource getEventSource(BioMaterial bioMaterial)
Get information about a biomaterial used as a source to this event.

Parameters:
bioMaterial - The biomaterial
Returns:
A BioMaterialEventSource object or null if the given biomaterial is not a source to the event
Since:
3.0
See Also:
addSource(BioMaterial)

isSource

public boolean isSource(BioMaterial bioMaterial)
Check if the given biomaterial has been used as a source in this event.

Parameters:
bioMaterial - The biomaterial to check

setSource

public BioMaterialEventSource setSource(BioMaterial parent)
Set a single parent item for this event. Any sources that are currently associated with it are removed and the used quantity is returned.

Parameters:
parent - The parent biomaterial, or null to remove all parents
Since:
3.0

addSource

public BioMaterialEventSource addSource(BioMaterial bioMaterial)
Add a biomaterial as a source to this event. If the given biomaterial already is a source, the existing information is returned. If this event already has sources the new source must be of the same type as the existing sources and the produced biomaterial.

Parameters:
bioMaterial - The biomaterial (null is not allowed)
Returns:
A BioMaterialEventSource object
Since:
3.0

addCheckedSource

private BioMaterialEventSource addCheckedSource(BioMaterial bioMaterial)

removeSource

public void removeSource(BioMaterial bioMaterial)
                  throws PermissionDeniedException,
                         InvalidDataException,
                         BaseException
Remove a biomaterial used as a source. Sources can only be specified if the produced biomaterial is a pooled biomaterial and this is a creation event.

Parameters:
bioMaterial - The biomaterial used as a source
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission for this event of use permission for the source
InvalidDataException - If this is not a creation event or if the produced biomaterial is not pooled or if the source biomaterial is of another type
BaseException - If there is another error
Since:
3.0

checkAllowedSource

private void checkAllowedSource(BioMaterial source,
                                boolean forAdd)
                         throws PermissionDeniedException,
                                InvalidDataException,
                                BaseException
Check if the biomaterial is allowed as a source.

Throws:
PermissionDeniedException
InvalidDataException
BaseException

clearSources

public void clearSources()
Clear the sources collection and return the used quantities to the source biomaterials.

Since:
3.0

clearSourcesExcept

private void clearSourcesExcept(BioMaterial parent)
Clear the sources collection and return the used quantities to the source biomaterials, except for the given biomaterial.

Parameters:
A - biomaterial that should already be a parent biomaterial or null to clear all sources
Since:
3.0.4

getSources

public ItemQuery<? extends BioMaterial> getSources()
Get a query that return all biomaterials used as sources for this event. To filter or sort on the used quantity or position columns use 'srcevt' as alias. For example to only return sources in position 2 and to order the result by used quantity:
query = event.getSources();
query.restrict(Expressions.gteq(
  Hql.property("srcevt", "position"), Expressions.integer(2))
);
query.order(Orders.asc(Hql.property("srcevt", "usedQuantity")));

NOTE! The filtering and ordering on the "srcevt" columns is only available in BASE 2.6 and later.

Returns:
An ItemQuery object

getEventSources

public SpecialQuery<BioMaterialEventSource> getEventSources()
Create a special query that return BioMaterialEventSource objects. The objects are not BasicItem:s but can be used to get information about and modify the source biomaterials used in the event. Note that the query may return objects that link to biomaterial that the logged in used doesn't have read access to.

Returns:
A special query
Since:
3.0

getEventSources

public List<BioMaterialEventSource> getEventSources(DbControl dc,
                                                    int position)
Utility method for finding all sources on a given bioassay position.

Parameters:
position - The position number (between 1 and PhysicalBioAssay.getSize().
Returns:
A list (empty if no sources are found)

getComment

public String getComment()
Get the comment about this event.

Returns:
The comment

setComment

public void setComment(String comment)
                throws PermissionDeniedException,
                       InvalidDataException
Set the comment about this event. The value may be null, but mustn't be longer than the value specified by the MAX_COMMENT_LENGTH constant.

Parameters:
comment - The new comment
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission on this event
InvalidDataException - If the comment is too long

getEntryDate

public Date getEntryDate()
Get the date this event was added to the database.

Specified by:
getEntryDate in interface Registered
Returns:
A Date object

getEventDate

public Date getEventDate()
Get the date this event was done in the lab.

Returns:
A Date object, or null if not known

setEventDate

public void setEventDate(Date eventDate)
                  throws PermissionDeniedException
Set the date this event was done in the lab.

Parameters:
eventDate - The date, or null if not known
Throws:
PermissionDeniedException - If the logged in user doesn't have write permission on this event

3.0.4: 2012-03-05