Version: 5.3.3-ice35-b63

OmeroBlitz API
Home Previous Up Next Index

omero::api::IContainer

Overview

[ "ami", "amd" ] interface IContainer extends ServiceInterface

Provides methods for dealing with the core Pojos of OME. Included are: Projects, Datasets, Images.

Read API

The names of the methods correlate to how the function operates:

Options Mechanism

The options are used to add some constraints to the generic method e.g. load hierarchy trees images for a given user. This mechanism should give us enough flexibility to extend the API if necessary, e.g. in some cases we might want to retrieve the images with or without annotations

Most methods take such an options map which is built on the client-side using the Parameters class. The currently supported options are:

Write API

As outlined in TODO, the semantics of the Omero write API are based on three rules:

  1. IObject-valued fields for which isLoaded() returns false are assumed filtered
  2. Collection-valued fields that are null are assumed filtered
  3. Collection-valued fields for which getDetails().isFiltered(String collectionName) returns true are assumed filtered. TODO: should we accept isFiltered for all fields?
In each of these cases, the server will reload that given field before attempting to save the graph.

For all write calls, the options map (see below) must contain the userId and the userGroupId for the newly created objects. TODO umask.

Operation Index

loadContainerHierarchy
Retrieves hierarchy trees rooted by a given node (unless orphan is specified -- See below)

This method also retrieves the Experimenters linked to the objects in the tree.

findContainerHierarchies
Retrieves hierarchy trees in various hierarchies that contain the specified Images.
getImages
Retrieve a user's (or all users') images within any given container.
getUserImages
Retrieves a user's images.
getImagesByOptions
Retrieves images by options.
getImagesBySplitFilesets
Given a list of IDs of certain entity types, calculates which filesets are split such that a non-empty proper subset of their images are referenced, directly or indirectly, as being included.
getCollectionCount
Counts the number of members in a collection for a given object.
retrieveCollection
Retrieves a collection with all members initialized (loaded).
createDataObject
Creates the specified data object.
createDataObjects
Convenience method to save network calls.
unlink
Removes links between OmeroDataObjects e.g Project-Dataset, Dataset-Image Note that the objects themselves aren't deleted, only the Link objects.
link
Convenience method for creating links.
updateDataObject
Updates a data object.
updateDataObjects
Convenience method to save network calls.

Operations

IObjectList loadContainerHierarchy(string rootType, sys::LongList rootIds, sys::Parameters options) throws ServerError

Retrieves hierarchy trees rooted by a given node (unless orphan is specified -- See below)

This method also retrieves the Experimenters linked to the objects in the tree. Similarly, all Images will be linked to their Pixel objects if included.

Note that objects are never duplicated. For example, if an Experimenter owns all the objects in the retrieved tree, then those objects will be linked to the same instance of model::Experimenter. Or if an Image is contained in more than one Dataset in the retrieved tree, then all enclosing model::Dataset objects will point to the same model::Image object. And so on.

Parameters

rootType
The type of the root node. Can be model::Project, model::Dataset, model::Screen or model::Plate. Cannot be null.
rootIds
The ids of the root nodes. Can be null if an Experimenter is specified in options, otherwise an Exception is thrown to prevent all images in the entire database from being downloaded.
options
Parameters as above. annotator, leaves, orphan, acquisition data used. acquisition data is only relevant for images and taken into account if the images are loaded. If rootNodeIds==null, experimenter|group must be set and filtering will be applied at the Class-level; e.g. to retrieve a user's Projects, or user's Datasets. If rootNodeIds!=null, the result will be filtered by the experimenter|group at the Image and intermediate levels if available. Due to the amount of data potentially linked a Screen/Plate, the leaves option is not taken into account when the root node is a model::Screen. orphan implies that objects which are not contained in an object of rootNodeType should also be returned.

Return Value

a set of hierarchy trees. The requested node as root and all of its descendants. The type of the returned value will be rootNodeType, unless orphan is specified in which case objects of type rootNodeType and below may be returned.

IObjectList findContainerHierarchies(string rootType, sys::LongList imageIds, sys::Parameters options) throws ServerError

Retrieves hierarchy trees in various hierarchies that contain the specified Images.

This method will look for all the containers containing the specified Images and then for all containers containing those containers and on up the container hierarchy.

This method returns a Set with all root nodes that were found. Every root node is linked to the found objects and so on until the leaf nodes, which are model::Image objects. Note that the type of any root node in the returned set can be the given rootNodeType, any of its containees or an model::Image.

For example, say that you pass in the ids of six Images: i1, i2, i3, i4, i5, i6. If the P/D/I hierarchy in the DB looks like this:

|                  __p1__                     
|                 /      \                    
|               _d1_    _d2_      d3          
|              /    \  /    \     |           
|             i1     i2     i3    i4    i5  i6

Then the returned set will contain p1, d3, i5, i6. All objects will be properly linked up.

Finally, this method will only retrieve the nodes that are connected in a tree to the specified leaf image nodes. Back to the previous example, if d1 contained image img500, then the returned object would not contain img500. In a similar way, if p1 contained ds300 and this dataset weren't linked to any of the i1, i2, i3, i4, i5, i6 images, then ds300 would not be part of the returned tree rooted by p1.

Parameters

rootType
top-most type which will be searched for Can be model::Project. Not null.
imageIds
Contains the ids of the Images that sit at the bottom of the trees. Not null.
options
Parameters as above. annotator used. experimenter|group may be applied at the top-level only or at each level in the hierarchy, but will not apply to the leaf (Image) level.

Return Value

A Set with all root nodes that were found.

ImageList getImages(string rootType, sys::LongList rootIds, sys::Parameters options) throws ServerError

Retrieve a user's (or all users') images within any given container. For example, all images in project, applying temporal filtering or pagination.

Parameters

rootType
A Class which will have its hierarchy searched for Images. Not null.
rootIds
A set of ids of type rootNodeType Not null.
options
Parameters as above. No notion of leaves. experimenter|group apply at the Image level. OPTIONS: - startTime and/or endTime should be Timestamp.valueOf("YYYY-MM-DD hh:mm:ss.ms");

limit and offset are applied at the Image-level. That is, calling with Dataset.class, limit == 10 and offset == 0 will first perform one query to get an effective set of rootNodeIds, then getImages will be called with an effective rootNodeType of Image.class and the new ids.

acquisition data is only relevant for images.

Return Value

A set of images.

ImageList getUserImages(sys::Parameters options) throws ServerError

Retrieves a user's images.

Parameters

options
Parameters as above. No notion of leaves. experimenter|group apply at the Image level and must be present.

Return Value

A set of images.

ImageList getImagesByOptions(sys::Parameters options) throws ServerError

Retrieves images by options.

Parameters

options
Parameters as above. No notion of leaves. experimenter|group apply at the Image level and must be present. OPTIONS: - startTime and/or endTime should be Timestamp.valueOf("YYYY-MM-DD hh:mm:ss.ms"). acquisition data is only relevant for images.

Return Value

A set of images.

IdBooleanLongListMapMap getImagesBySplitFilesets(StringLongListMap included, sys::Parameters options) throws ServerError

Given a list of IDs of certain entity types, calculates which filesets are split such that a non-empty proper subset of their images are referenced, directly or indirectly, as being included. The return value lists both the fileset IDs and the image IDs in ascending order, the image ID lists separated by if they were included. Warning: following discussion in trac ticket 11019 the return type may be changed.

Parameters

included
the entities included
options
parameters, presently ignored

Return Value

the partially included filesets

sys::CountMap getCollectionCount(string type, string property, sys::LongList ids, sys::Parameters options) throws ServerError

Counts the number of members in a collection for a given object. For example, if you wanted to retrieve the number of Images contained in a Dataset you would pass TODO.

Parameters

type
The fully-qualified classname of the object to be tested
property
Name of the property on that class, omitting getters and setters.
ids
Set of Longs, the ids of the objects to test
options
Parameters. Unused.

Return Value

A map from id integer to count integer

IObjectList retrieveCollection(model::IObject obj, string collectionName, sys::Parameters options) throws ServerError

Retrieves a collection with all members initialized (loaded). This is useful when a collection has been nulled in a previous query.

Parameters

obj
Can be unloaded.
collectionName
public final static String from the IObject.class
options
Parameters. Unused.

Return Value

An initialized collection.

model::IObject createDataObject(model::IObject obj, sys::Parameters options) throws ServerError

Creates the specified data object.

A placeholder parent object is created if the data object is to be put in a collection.

For example, if the object is a Dataset, we first create a Project as parent then we set the Dataset parent as follows: //pseudo-code TODO Project p = new Project(id,false); dataset.addProject(p); then for each parent relationship a DataObject omero::model::ILink is created.

Parameters

obj
IObject. Supported: Project, Dataset, Annotation, Group, Experimenter. Not null.
options
Parameters as above.

Return Value

the created object

IObjectList createDataObjects(IObjectList dataObjects, sys::Parameters options) throws ServerError

Convenience method to save network calls. Loops over the array of IObjects calling createDataObject.

Parameters

dataObjects
Array of Omero IObjects
options
Parameters as above.

See Also

createDataObject(IObject, Parameters)

void unlink(IObjectList links, sys::Parameters options) throws ServerError

Removes links between OmeroDataObjects e.g Project-Dataset, Dataset-Image Note that the objects themselves aren't deleted, only the Link objects.

Parameters

links
Not null.
options
Parameters as above.

IObjectList link(IObjectList links, sys::Parameters options) throws ServerError

Convenience method for creating links. Functionality also available from createDataObject

Parameters

links
Array of links to be created.
options
Parameters as above.

Return Value

the created links

model::IObject updateDataObject(model::IObject obj, sys::Parameters options) throws ServerError

Updates a data object.

To link or unlink objects to the specified object, we should call the methods link or unlink. TODO Or do we use for example dataset.setProjects(set of projects) to add. Tink has to be set as follows dataset->project and project->dataset. Alternatively, you can make sure that the collection is exactly how it should be in the database. If you can't guarantee this, it's best to send all your collections back as null

Parameters

obj
Pojos-based IObject. Supported: Project, Dataset, Annotation, Group, Experimenter.
options
Parameters as above.

Return Value

created data object

IObjectList updateDataObjects(IObjectList objs, sys::Parameters options) throws ServerError

Convenience method to save network calls. Loops over the array of IObjects calling updateDataObject.

Parameters

options
Parameters as above.

Return Value

created data objects.

See Also

updateDataObject

Home Previous Up Next Index