net.sf.basedb.core
Class Experiment

java.lang.Object
  net.sf.basedb.core.BasicItem<D>
      net.sf.basedb.core.OwnedItem<D>
          net.sf.basedb.core.SharedItem<D>
              net.sf.basedb.core.CommonItem<ExperimentData>
                  net.sf.basedb.core.Experiment

All Implemented Interfaces:

AccessControlled, Controlled, DiskConsumable, Identifiable, Nameable, Ownable, Registered, Removable, Shareable, Transactional, ToTransferable<ExperimentInfo>

public class Experiment
extends CommonItem<ExperimentData>
implements DiskConsumable, Transactional, ToTransferable<ExperimentInfo>, Registered

An experiment is the starting point of the analysis in BASE. An experiment is linked to zero or more RawBioAssay:s of the same RawDataType as itself. It is not possible to mix raw data types. A root Transformation is used to calculate the first set of intensities from the raw data. The intensities are stored in a root BioAssaySet.

Then, it is possible to apply more transformations using the root bioassayset as a source. Each transformation may create new bioassaysets, from which it is possible to apply new transformations and so on.

Version:

2.0

Author:

Nicklas

Last modified

$Date: 2010-05-17 12:44:31 +0200 (Mon, 17 May 2010) $

Nested Class Summary

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

Transactional.Action

Field Summary

private long	addedBytes
static int	MAX_ABSTRACT_LENGTH The maximum length of the abstract property that can be stored in the database.
static int	MAX_AFFILIATIONS_LENGTH The maximum length of the affiliations property that can be stored in the database.
static int	MAX_AUTHORS_LENGTH The maximum length of the authors property that can be stored in the database.
static int	MAX_EXPERIMENT_DESIGN_LENGTH The maximum length of the experimentDesign property that can be stored in the database.
static int	MAX_EXPERIMENT_TYPE_LENGTH The maximum length of the experimentType property that can be stored in the database.
static int	MAX_PUBLICATION_LENGTH The maximum length of the publication property that can be stored in the database.
static int	MAX_PUBMEDID_LENGTH The maximum length of the pubMedId property that can be stored in the database.
static int	MAX_TITLE_LENGTH The maximum length of the title property that can be stored in the database.
static Item	TYPE The type of item represented by this class.
private long	updatedBytes

Fields inherited from interface net.sf.basedb.core.Nameable

MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH

Constructor Summary

Experiment(ExperimentData data)
Creates a new experiment item from the given data.

Method Summary

(package private) void	addBytes(long bytes)
void	addExperimentalFactor(AnnotationType annotationType) Add an annotation type as an experimental factor to this experiment.
void	addRawBioAssay(RawBioAssay rawBioAssay) Add a raw bioassay to this experiment.
String	getAbstract() Get the abstract text for the publication for this experiment.
String	getAffiliations() Get the affiliations for this experiment.
String	getAuthors() Get the authors of the publication for this experiment.
ItemQuery<BioAssaySet>	getBioAssaySets() Get a query that return all bioassaysets in this experiment.
static Experiment	getById(DbControl dc, int id) Get an Experiment item when you know the id.
long	getBytes() Get the absolute number of bytes this item uses.
long	getDifference() Get the number of bytes this items now is using compared to when it was loaded from the database.
Directory	getDirectory() Get the associated directory where it is recommended that plugins store files that are related to this experiment.
Date	getEntryDate() Get the date that the item was registered in the database.
ItemQuery<AnnotationType>	getExperimentalFactors() Get a query that returns all annotation types used as experimental factors for this experiment.
String	getExperimentDesign() Get the a text describing the experimental design.
String	getExperimentType() Get the a text describing the experiment type.
Location	getLocation() Always Location.PRIMARY.
static Experiment	getNew(DbControl dc, RawDataType rawDataType) Create a new Experiment item.
String	getPublication() Get the publication text.
Date	getPublicationDate() Get the date this experiment was published.
String	getPubMedId() Get the PubMed ID of the publication.
static ItemQuery<Experiment>	getQuery() Get a query configured to retrieve experiments
String	getQuotaTypeSystemId() Always QuotaType.EXPERIMENT.
ItemQuery<RawBioAssay>	getRawBioAssays() Get a query that returns the raw bioassays used in this experiment.
RawDataType	getRawDataType() Get the raw data type this experiment uses for the raw data.
ItemQuery<Transformation>	getRootTransformations() Get a query that return all root transformations in this experiment.
String	getTitle() Get the title for the publication for this experiment.
ItemQuery<Transformation>	getTransformations() Get a query that return all transformations including root transformations in this experiment.
Item	getType() Get the type of item represented by the object.
(package private) VirtualDb	getVirtualDb()
boolean	isUsing(RawBioAssay rawBioAssay) Check if a raw bioassay is used in this experiment.
Transformation	newTransformation(Job job, Collection<RawBioAssay> rawSources) Create a new root transformation for this experiment.
(package private) void	onBeforeCommit(Transactional.Action action) If a project is active, automatically share the new item according to the settings of that project, unless a project or item key has been explicitely set (including null).
void	removeExperimentalFactor(AnnotationType annotationType) Remove an annotation type from the experimental factors for this experiment.
void	removeRawBioAssay(RawBioAssay rawBioAssay) Remove a raw bioassay from this experiment.
void	setAbstract(String theAbstract) Set the abstract text for the publication of this experiment.
void	setAffiliations(String affiliations) Set the affiliations for this experiment.
void	setAuthors(String authors) Set the authors of the publication for this experiment.
void	setDirectory(Directory directory) Set the directory where it is recommended that plugins store files that are related to this experiment.
void	setExperimentDesign(String experimentDesign) Set a text describing the experimental design.
void	setExperimentType(String experimentType) Set a text describing the experiment type.
void	setPublication(String publication) Set publication text.
void	setPublicationDate(Date publicationDate) Set the date this experiment was published.
void	setPubMedId(String pubMedId) Set the PubMed ID of the publication.
private void	setRawDataType(RawDataType rawDataType) Set the raw data type.
void	setTitle(String title) Set the title for the publication of this experiment.
ExperimentInfo	toTransferable(ExperimentInfo info) Transfer the internal state to a transferable object.
private void	unlinkJobs() Unlink jobs from this experiment that are references from other items NOT PART of the experiment.
boolean	useDifference() TRUE if the experiment has been saved to the database, FALSE otherwise.

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

getDescription, getName, isRemoved, setDescription, setName, setRemoved, toTransferable

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

getItemKey, getProjectKey, initPermissions, isShared, setItemKey, setProjectKey, toTransferable

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

getOwner, isOwner, setOwner, takeOwnership, toTransferable

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

addUsingItems, addUsingItems, checkPermission, equals, getData, getDbControl, getId, getPermissions, getPluginPermissions, getSessionControl, getUsingItems, getVersion, hashCode, hasPermission, isDetached, isInDatabase, isUsed, onAfterCommit, onAfterInsert, onRollback, setDbControl, setProjectDefaults, 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.Ownable

getOwner, isOwner, setOwner, takeOwnership

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.EXPERIMENT, getType()

MAX_AUTHORS_LENGTH

public static final int MAX_AUTHORS_LENGTH

The maximum length of the authors property that can be stored in the database. Check the length against this value before calling the setAuthors(String) method to avoid exceptions.

See Also:

Constant Field Values

MAX_AFFILIATIONS_LENGTH

public static final int MAX_AFFILIATIONS_LENGTH

The maximum length of the affiliations property that can be stored in the database. Check the length against this value before calling the setAffiliations(String) method to avoid exceptions.

See Also:

Constant Field Values

MAX_TITLE_LENGTH

public static final int MAX_TITLE_LENGTH

The maximum length of the title property that can be stored in the database. Check the length against this value before calling the setTitle(String) method to avoid exceptions.

See Also:

Constant Field Values

MAX_ABSTRACT_LENGTH

public static final int MAX_ABSTRACT_LENGTH

The maximum length of the abstract property that can be stored in the database. Check the length against this value before calling the setAbstract(String) method to avoid exceptions.

See Also:

Constant Field Values

MAX_PUBLICATION_LENGTH

public static final int MAX_PUBLICATION_LENGTH

The maximum length of the publication property that can be stored in the database. Check the length against this value before calling the setPublication(String) method to avoid exceptions.

See Also:

Constant Field Values

MAX_EXPERIMENT_TYPE_LENGTH

public static final int MAX_EXPERIMENT_TYPE_LENGTH

The maximum length of the experimentType property that can be stored in the database. Check the length against this value before calling the setExperimentType(String) method to avoid exceptions.

See Also:

Constant Field Values

MAX_EXPERIMENT_DESIGN_LENGTH

public static final int MAX_EXPERIMENT_DESIGN_LENGTH

The maximum length of the experimentDesign property that can be stored in the database. Check the length against this value before calling the setExperimentDesign(String) method to avoid exceptions.

See Also:

Constant Field Values

MAX_PUBMEDID_LENGTH

public static final int MAX_PUBMEDID_LENGTH

The maximum length of the pubMedId property that can be stored in the database. Check the length against this value before calling the setPubMedId(String) method to avoid exceptions.

See Also:

Constant Field Values

addedBytes

private long addedBytes

updatedBytes

private long updatedBytes

Constructor Detail

Experiment

Experiment(ExperimentData data)

Creates a new experiment item from the given data.

Parameters:

data - the data

Method Detail

getNew

public static Experiment getNew(DbControl dc,
                                RawDataType rawDataType)
                         throws BaseException

Create a new Experiment item.

Parameters:

dc - The DbControl which will be used for permission checking and database access.

rawDataType - The data type of the raw data used in this experiment

Returns:

The new Experiment item

Throws:

BaseException - If there is an error

getById

public static Experiment getById(DbControl dc,
                                 int id)
                          throws ItemNotFoundException,
                                 PermissionDeniedException,
                                 BaseException

Get an Experiment 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 Experiment item

Throws:

ItemNotFoundException - If an item with the specified id is not found

PermissionDeniedException - If the logged in user doesn't have Permission.READ permission to the item

BaseException - If there is another error

getQuery

public static ItemQuery<Experiment> getQuery()

Get a query configured to retrieve experiments

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.

Specified by:

getType in interface Identifiable

Returns:

A value indicating the type of item

useDifference

public boolean useDifference()

TRUE if the experiment has been saved to the database, FALSE otherwise.

Specified by:

useDifference in interface DiskConsumable

Returns:

TRUE if the item reports the difference, FALSE if it reports the absolute

See Also:

DiskConsumable.getBytes(), DiskConsumable.getDifference()

getBytes

public long getBytes()

Description copied from interface: DiskConsumable

Get the absolute number of bytes this item uses. All items must report this number.

Specified by:

getBytes in interface DiskConsumable

Returns:

The absolute number of bytes the item uses

See Also:

DiskConsumable.useDifference(), DiskConsumable.getDifference()

getDifference

public long getDifference()

Description copied from interface: DiskConsumable

Get the number of bytes this items now is using compared to when it was loaded from the database. This number may be negative if the item is now using less bytes than before. An item doesn't have to report this value if DiskConsumable.useDifference() returns FALSE.

Specified by:

getDifference in interface DiskConsumable

Returns:

The difference in bytes between now and when the item was loaded, or 0 if this item doesn't report differences

addBytes

void addBytes(long bytes)

getQuotaTypeSystemId

public String getQuotaTypeSystemId()

Always QuotaType.EXPERIMENT.

Specified by:

getQuotaTypeSystemId in interface DiskConsumable

Returns:

The systemid of the QuotaType

getLocation

public Location getLocation()

Always Location.PRIMARY.

Specified by:

getLocation in interface DiskConsumable

Returns:

The location

getEntryDate

public Date getEntryDate()

Description copied from interface: Registered

Get the date that the item was registered in the database.

Specified by:

getEntryDate in interface Registered

Returns:

A date or null if this is not known

onBeforeCommit

void onBeforeCommit(Transactional.Action action)
              throws BaseException

Description copied from class: SharedItem

If a project is active, automatically share the new item according to the settings of that project, unless a project or item key has been explicitely set (including null).

Overrides:

onBeforeCommit in class SharedItem<ExperimentData>

Throws:

BaseException - If there is another error

See Also:

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

toTransferable

public ExperimentInfo toTransferable(ExperimentInfo info)

Description copied from interface: ToTransferable

Transfer the internal state to a transferable object. The method should return the same object that is passed in as an argument.

Specified by:

toTransferable in interface ToTransferable<ExperimentInfo>

Parameters:

info - The transferable object to use

Returns:

The transferable object with values set.

Since:

2.5

getRawDataType

public RawDataType getRawDataType()

Get the raw data type this experiment uses for the raw data. The raw data type cannot be changed once the experiment has been created.

Returns:

A RawDataType object

setRawDataType

private void setRawDataType(RawDataType rawDataType)
                     throws InvalidDataException

Set the raw data type. It cannot be changed.

Parameters:

rawDataType - The raw data type, null is not allowed

Throws:

InvalidDataException

getVirtualDb

VirtualDb getVirtualDb()

getTitle

public String getTitle()

Get the title for the publication for this experiment.

setTitle

public void setTitle(String title)
              throws PermissionDeniedException,
                     InvalidDataException

Set the title for the publication of this experiment. The value may be null, but mustn't be longer than the value specified by the MAX_TITLE_LENGTH constant.

Parameters:

title - The new title

Throws:

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

InvalidDataException - If the text is too long

getDirectory

public Directory getDirectory()
                       throws PermissionDeniedException,
                              BaseException

Get the associated directory where it is recommended that plugins store files that are related to this experiment.

Returns:

The Directory item

Throws:

PermissionDeniedException - This exception is thrown if the logged in user doesn't have read permission to the item

BaseException - If there is another error

setDirectory

public void setDirectory(Directory directory)
                  throws PermissionDeniedException,
                         InvalidUseOfNullException

Set the directory where it is recommended that plugins store files that are related to this experiment.

Parameters:

directory - The new Directory, or null

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission to the experiment or use permission to the directory

InvalidUseOfNullException

getAbstract

public String getAbstract()

Get the abstract text for the publication for this experiment.

setAbstract

public void setAbstract(String theAbstract)
                 throws PermissionDeniedException,
                        InvalidDataException

Set the abstract text for the publication of this experiment. The value may be null, but mustn't be longer than the value specified by the MAX_ABSTRACT_LENGTH constant.

Parameters:

theAbstract - The new abstract text

Throws:

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

InvalidDataException - If the text is too long

getAuthors

public String getAuthors()

Get the authors of the publication for this experiment.

setAuthors

public void setAuthors(String authors)
                throws PermissionDeniedException,
                       InvalidDataException

Set the authors of the publication for this experiment. The value may be null, but mustn't be longer than the value specified by the MAX_AUTHORS_LENGTH constant.

Parameters:

authors - The new authors text

Throws:

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

InvalidDataException - If the text is too long

getAffiliations

public String getAffiliations()

Get the affiliations for this experiment.

setAffiliations

public void setAffiliations(String affiliations)
                     throws PermissionDeniedException,
                            InvalidDataException

Set the affiliations for this experiment. The value may be null, but mustn't be longer than the value specified by the MAX_AFFILIATIONS_LENGTH constant.

Parameters:

affiliations - The new affiliations text

Throws:

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

InvalidDataException - If the text is too long

getExperimentDesign

public String getExperimentDesign()

Get the a text describing the experimental design.

setExperimentDesign

public void setExperimentDesign(String experimentDesign)
                         throws PermissionDeniedException,
                                InvalidDataException

Set a text describing the experimental design. The value may be null, but mustn't be longer than the value specified by the MAX_EXPERIMENT_DESIGN_LENGTH constant.

Parameters:

experimentDesign - The new experimental design

Throws:

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

InvalidDataException - If the text is too long

getExperimentType

public String getExperimentType()

Get the a text describing the experiment type.

setExperimentType

public void setExperimentType(String experimentType)
                       throws PermissionDeniedException,
                              InvalidDataException

Set a text describing the experiment type. The value may be null, but mustn't be longer than the value specified by the MAX_EXPERIMENT_TYPE_LENGTH constant.

Parameters:

experimentType - The new experiment type

Throws:

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

InvalidDataException - If the text is too long

getPublication

public String getPublication()

Get the publication text.

setPublication

public void setPublication(String publication)
                    throws PermissionDeniedException,
                           InvalidDataException

Set publication text. The value may be null, but mustn't be longer than the value specified by the MAX_PUBLICATION_LENGTH constant.

Parameters:

publication - The publication text

Throws:

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

InvalidDataException - If the text is too long

getPubMedId

public String getPubMedId()

Get the PubMed ID of the publication.

setPubMedId

public void setPubMedId(String pubMedId)
                 throws PermissionDeniedException,
                        InvalidDataException

Set the PubMed ID of the publication. The value may be null, but mustn't be longer than the value specified by the MAX_PUBMEDID_LENGTH constant.

Parameters:

pubMedId - The PubMed ID

Throws:

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

InvalidDataException - If the text is too long

getPublicationDate

public Date getPublicationDate()

Get the date this experiment was published.

Returns:

A Date object, or null if not known

setPublicationDate

public void setPublicationDate(Date publicationDate)
                        throws PermissionDeniedException

Set the date this experiment was published.

Parameters:

publicationDate - The date, or null if not known

Throws:

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

addRawBioAssay

public void addRawBioAssay(RawBioAssay rawBioAssay)
                    throws PermissionDeniedException,
                           InvalidDataException

Add a raw bioassay to this experiment. Spots must have been added to the raw bioassay and it must have the same RawDataType as this experiment.

Parameters:

rawBioAssay - The rawBioAssay to add to this experiment

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for the experiment and Permission.USE for the raw bioassay

InvalidDataException - If the rawBioAssay is null, or has a different raw data type

removeRawBioAssay

public void removeRawBioAssay(RawBioAssay rawBioAssay)
                       throws PermissionDeniedException,
                              InvalidDataException

Remove a raw bioassay from this experiment.

Parameters:

rawBioAssay - The rawBioAssay to remove from this experiment

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for the experiment

InvalidDataException - If the rawBioAssay is null

isUsing

public boolean isUsing(RawBioAssay rawBioAssay)

Check if a raw bioassay is used in this experiment.

Parameters:

rawBioAssay - The raw bioassay to look for

Returns:

TRUE if the raw bioassay is used in the experiment, FALSE otherwise

getRawBioAssays

public ItemQuery<RawBioAssay> getRawBioAssays()

Get a query that returns the raw bioassays used in this experiment.

Returns:

An ItemQuery object

newTransformation

public Transformation newTransformation(Job job,
                                        Collection<RawBioAssay> rawSources)
                                 throws PermissionDeniedException,
                                        InvalidDataException,
                                        BaseException

Create a new root transformation for this experiment.

Parameters:

job - The job that executed the transformation

rawSources - The raw bioassays used as source bioassays

Throws:

PermissionDeniedException - If the logged in user doesn't have use permission for the experiment

InvalidDataException - If any of the raw bioassays are not part of the experiment

BaseException - If there is another error

getTransformations

public ItemQuery<Transformation> getTransformations()

Get a query that return all transformations including root transformations in this experiment.

Returns:

An ItemQuery object

See Also:

Transformation.getQuery(Experiment), getRootTransformations()

getRootTransformations

public ItemQuery<Transformation> getRootTransformations()

Get a query that return all root transformations in this experiment. A root transformation is a transformation that doesn't have a source bioassayset.

Returns:

An ItemQuery object

See Also:

getTransformations(), Transformation.getSource()

getBioAssaySets

public ItemQuery<BioAssaySet> getBioAssaySets()

Get a query that return all bioassaysets in this experiment.

Returns:

An ItemQuery object

See Also:

BioAssaySet.getQuery(Experiment)

addExperimentalFactor

public void addExperimentalFactor(AnnotationType annotationType)
                           throws PermissionDeniedException,
                                  InvalidDataException

Add an annotation type as an experimental factor to this experiment.

Parameters:

annotationType - The annotation type to add to this experiment

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for the experiment and Permission.USE for the annotation type

InvalidDataException - If the annotationType is null

removeExperimentalFactor

public void removeExperimentalFactor(AnnotationType annotationType)
                              throws PermissionDeniedException,
                                     InvalidDataException

Remove an annotation type from the experimental factors for this experiment.

Parameters:

annotationType - The annotation type to remove from this experiment

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.WRITE permission for the experiment

InvalidDataException - If the annotationType is null

getExperimentalFactors

public ItemQuery<AnnotationType> getExperimentalFactors()

Get a query that returns all annotation types used as experimental factors for this experiment.

Returns:

An ItemQuery object

unlinkJobs

private void unlinkJobs()

Unlink jobs from this experiment that are references from other items NOT PART of the experiment. Without the unlinking it is not possible to delete the experiment because it will not be possible to delete the jobs that are part of.

Since:

2.7

See Also:

ExperimentData.getJobs()