net.sf.basedb.core
Class Transformation

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

All Implemented Interfaces:

AccessControlled, Identifiable, Nameable, Removable

public class Transformation
extends ChildItem<TransformationData>
implements Nameable, Removable

A transformation represents an analysis step for an Experiment. There are two types of transformations. A root transformation is used to calculate the initial set of intensities from a set of RawBioAssay:s. The result of a transformation is usually one or more BioAssaySet:s. The other type of transformation takes a bioassayset as the source and recalculates the intensities, applies a filter or does something else.

A transformation is created by either the Experiment.newTransformation(Job, Collection) method or the BioAssaySet.newTransformation(Job) method.

Version:

2.0

Author:

Nicklas

See Also:

Experiment.newTransformation(Job, Collection), BioAssaySet.newTransformation(Job)

Last modified

$Date: 2009-04-06 14:52:39 +0200 (Mon, 06 Apr 2009) $

Field Summary

private Job	job
private Map<String,DataCube>	namedCubes Internal cache of named cubes used by the newProduct method.
private Map<String,DataCubeLayer>	namedLayers Internal cache of named layers used by the newProduct method.
static Item	TYPE The type of item represented by this class.

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

MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH

Constructor Summary

Transformation(TransformationData data)
Creates a new experiment item from the given data.

Method Summary

private void	deleteProducts() Delete all product bioassaysets.
static Transformation	getById(DbControl dc, int id) Get a Transformation item when you know the id.
String	getDescription() Get the description for the item.
Experiment	getExperiment() Get the experiment this transformation belongs to.
Job	getJob() Get the job that executed this transformation.
String	getName() Get the name of the item.
(package private) static Transformation	getNew(DbControl dc, Experiment experiment, Job job) Create a new Transformation item.
(package private) Permission	getPermissionForWriteDeleteAndCreate() USE permission is enough to be able to manage transformations.
ItemQuery<BioAssaySet>	getProducts() Get a query that return all bioassaysets created by this transformation.
static ItemQuery<Transformation>	getQuery(BioAssaySet bioAssaySet) Get a query configured to retrieve transformations using the given bioassayset as source.
static ItemQuery<Transformation>	getQuery(Experiment experiment) Get a query configured to retrieve transformations for a given experiment.
ItemQuery<RawBioAssay>	getRawSources() Get a query that returns the raw bioassay sources used by this transformation.
(package private) SharedData	getSharedParent() Get the experiment.
BioAssaySet	getSource() Get the source bioassayset used by this transformation.
Item	getType() Get the type of item represented by the object.
boolean	isRemoved() Check if the removed flag is set for this item.
BioAssaySet	newProduct(String namedCube, String namedLayer, boolean createChildBioAssays) Create a new product bioassayset from this transformation.
(package private) void	onBeforeCommit(Transactional.Action action) Delete the product bioassaysets when deleting this transction.
void	setDescription(String description) Set the description for the item.
private void	setExperiment(Experiment experiment) Set the experiment.
private void	setJob(Job job) Set the job that executed this transformation.
void	setName(String name) Set the name of the item.
(package private) void	setRawSources(Collection<RawBioAssay> rawBioAssays) Set the raw bioassay sources used in this transformation.
void	setRemoved(boolean removed) Set the removed flag for this item.
(package private) void	setSource(BioAssaySet bioAssaySet) Set the source bioassayset.

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

getPluginPermissions, initPermissions

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

job

private Job job

namedCubes

private Map<String,DataCube> namedCubes

Internal cache of named cubes used by the newProduct method.

namedLayers

private Map<String,DataCubeLayer> namedLayers

Internal cache of named layers used by the newProduct method.

Constructor Detail

Transformation

Transformation(TransformationData data)

Creates a new experiment item from the given data.

Parameters:

data - the data

Method Detail

getNew

static Transformation getNew(DbControl dc,
                             Experiment experiment,
                             Job job)
                      throws BaseException

Create a new Transformation item. No source has been specified. A caller should use either: setSource(BioAssaySet) or setRawSources(Collection).

Parameters:

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

experiment - The experiment

job - The job that executed the transformation

Returns:

The new Transformation item

Throws:

BaseException - If there is another error

See Also:

Experiment.newTransformation(Job, Collection), BioAssaySet.newTransformation(Job)

getById

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

Get a Transformation 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 Transformation 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<Transformation> getQuery(Experiment experiment)
                                          throws InvalidDataException

Get a query configured to retrieve transformations for a given experiment.

Parameters:

experiment - The experiment to retreive transformations for, null is not allowed

Returns:

An ItemQuery object

Throws:

InvalidDataException - If required parameter is null.

getQuery

public static ItemQuery<Transformation> getQuery(BioAssaySet bioAssaySet)
                                          throws InvalidDataException

Get a query configured to retrieve transformations using the given bioassayset as source.

Parameters:

bioAssaySet - The source bioassayset to retreive transformations for, null is not allowed

Returns:

An ItemQuery object

Throws:

InvalidDataException - If required parameter is null.

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

getName

public String getName()

Description copied from interface: Nameable

Get the name of the item.

Specified by:

getName in interface Nameable

Returns:

A String with the name of the item

setName

public void setName(String name)
             throws PermissionDeniedException,
                    InvalidDataException

Description copied from interface: Nameable

Set the name of the item. The name cannot be null and mustn't be longer than the value specified by the Nameable.MAX_NAME_LENGTH constant.

Specified by:

setName in interface Nameable

Parameters:

name - The new name for the item

Throws:

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

InvalidDataException - If the name is null or longer than specified by the Nameable.MAX_NAME_LENGTH constant

getDescription

public String getDescription()

Description copied from interface: Nameable

Get the description for the item.

Specified by:

getDescription in interface Nameable

Returns:

A String with a description of the item

setDescription

public void setDescription(String description)
                    throws PermissionDeniedException,
                           InvalidDataException

Description copied from interface: Nameable

Set the description for the item. The description can be null but mustn't be longer than the value specified by the Nameable.MAX_DESCRIPTION_LENGTH constant.

Specified by:

setDescription in interface Nameable

Parameters:

description - The new description for the item

Throws:

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

InvalidDataException - If the description longer than specified by the Nameable.MAX_DESCRIPTION_LENGTH constant

isRemoved

public boolean isRemoved()

Description copied from interface: Removable

Check if the removed flag is set for this item.

Specified by:

isRemoved in interface Removable

Returns:

TRUE if the item is flagged as removed, FALSE otherwise

setRemoved

public void setRemoved(boolean removed)
                throws PermissionDeniedException

Description copied from interface: Removable

Set the removed flag for this item.

Specified by:

setRemoved in interface Removable

Parameters:

removed - TRUE if the item should be flagged as removed, FALSE otherwise

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.DELETE permission for setting the flag to TRUE or Permission.WRITE permission for setting the flag to FALSE

onBeforeCommit

void onBeforeCommit(Transactional.Action action)
              throws BaseException

Delete the product bioassaysets when deleting this transction. Set the experiment for the job when creating this transction.

Overrides:

onBeforeCommit in class BasicItem<TransformationData>

Throws:

BaseException - If there is an error

See Also:

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

getSharedParent

SharedData getSharedParent()

Get the experiment.

Specified by:

getSharedParent in class ChildItem<TransformationData>

Returns:

The parent item

getPermissionForWriteDeleteAndCreate

Permission getPermissionForWriteDeleteAndCreate()

USE permission is enough to be able to manage transformations.

Overrides:

getPermissionForWriteDeleteAndCreate in class ChildItem<TransformationData>

getExperiment

public Experiment getExperiment()
                         throws PermissionDeniedException,
                                BaseException

Get the experiment this transformation belongs to.

Returns:

An Experiment object

Throws:

PermissionDeniedException - If the logged in user doesn't have read permission to the experiment

BaseException - If there is another error

setExperiment

private void setExperiment(Experiment experiment)

Set the experiment. This cannot be changed after the transformation has been created.

getSource

public BioAssaySet getSource()
                      throws PermissionDeniedException,
                             BaseException

Get the source bioassayset used by this transformation.

Returns:

A BioAssaySet item, or null if this is a root transformation

Throws:

PermissionDeniedException - If the logged in user doesn't have read permission to the experiment

BaseException - If there is another error

See Also:

getRawSources()

setSource

void setSource(BioAssaySet bioAssaySet)

Set the source bioassayset. This cannot be changed after the transformation has been created.

See Also:

BioAssaySet.newTransformation(Job)

getRawSources

public ItemQuery<RawBioAssay> getRawSources()

Get a query that returns the raw bioassay sources used by this transformation. It is only a root transformation that has raw bioassays as sources, other transformations has a source BioAssaySet.

Returns:

An ItemQuery object

See Also:

getSource()

setRawSources

void setRawSources(Collection<RawBioAssay> rawBioAssays)
             throws InvalidDataException

Set the raw bioassay sources used in this transformation. Can only be specified for a root transformation. All raw bioassays must be members of the experiment.

Throws:

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

See Also:

Experiment.newTransformation(Job, Collection), Experiment.isUsing(RawBioAssay)

getJob

public Job getJob()
           throws PermissionDeniedException,
                  BaseException

Get the job that executed this transformation.

Returns:

A Job object, ot null if this transformation wasn't executed by a job

Throws:

PermissionDeniedException - If the logged in user doesn't have read permission to the experiment

BaseException - If there is another error

setJob

private void setJob(Job job)

Set the job that executed this transformation. Once set it can't be changed.

newProduct

public BioAssaySet newProduct(String namedCube,
                              String namedLayer,
                              boolean createChildBioAssays)
                       throws PermissionDeniedException,
                              InvalidDataException,
                              BaseException

Create a new product bioassayset from this transformation. The transformation mustn't have been committed to the database. The bioassayset can use either the same data cube/layer as the source bioassayset is using, a new data cube/layer or a data cube/layer that has previously been created by this method. The names specified here are only valid for the current session and are only needed if the transformation must create more than one bioassayset in a different data cube than it's source bioassayset.

Transformation t = ...

// Use same data cube, but a new layer; automatically create child bioassays
BioAssaySet bas = t.newProduct(null, "new", true);

// Use same data cube and layer; automatically create child bioassays
BioAssaySet filtered = t.newProduct(null, null, true);

// Use new data cube and layer; automatic creation of 
// child bioassays is not supported
BioAsssySet merged = t.newProduct("new", "new", false);

// Create four new bioassaysets using two datacubes, one
// with two layers and one with one layer
BioAssaySet bas1 = t.newProduct("cube1", "layer1", false);
BioAssaySet bas2 = t.newProduct("cube1", "layer2", false);
BioAssaySet bas3 = t.newProduct("cube2", "layer3", false);
BioAssaySet bas4 = t.newProduct("cube2", "layer3", false);

Note that the name of the layer is checked first, so we can't have the layers with the same name in two different cubes. For example the following call won't work:

// Don't! We bas3 is now using the same cube and layer as bas1
BioAssaySet bas3 = t.newProduct("cube2", "layer1", false);

Parameters:

namedCube - The name of the data cube where the new bioassayset should store/find it's data. If no data cube with the specified name exists a new data cube is created. Specify 'null' to use the same data cube as the source bioassayset.

namedLayer - The name of the data cube layer where the new bioassayset should store/find it's data. If no layer with the specified name exists a new layer is created. Specify 'null' to use the same layer as the source bioassayset.

createChildBioAssays - TRUE to create one child bioassay for each bioassay in the source bioassay set. This requires that the product is created in the same data cube as the source bioassay set, ie. namedCube should be null

Returns:

The new bioassayset

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission for the experiment this transformation belongs to or if this transformation has already been committed to the database

InvalidDataException - If the layer is null or not part of the same experiment as this transformation

BaseException - If there is another error

getProducts

public ItemQuery<BioAssaySet> getProducts()

Get a query that return all bioassaysets created by this transformation.

Returns:

An ItemQuery object

See Also:

BioAssaySet.getQuery(Transformation)

deleteProducts

private void deleteProducts()

Delete all product bioassaysets. Called by onBeforeCommit when the transformation is deleted.