Graph requests

Overview

The Blitz API offers several requests that are subclasses of GraphQuery. These may be submitted to the server for asynchronous processing of linked graphs of OMERO model objects. This section gives a brief overview of the graph requests and their purpose. Follow the links to see more details.

Querying the model object graph

GraphQuery (base class)

The parent of the requests below, it includes a targetObjects property that specifies from which model objects to start processing. The LegalGraphTargets request can be used to determine which types of model object may be targeted.

DiskUsage2

Report on the disk usage of the target objects and their contents by type, user and group. Includes a targetClasses property to allow specifying every visible instance of a type.

FindParents

Find the parents of the target objects, both direct and indirect. typesOfParents specifies the types of parents to report. stopBefore specifies types of model object to avoid in traversing the linked graph upward: those subgraphs are ignored unless otherwise reachable.

FindChildren

Find the children of the target objects, both direct and indirect. typesOfChildren specifies the types of children to report. stopBefore specifies types of model object to avoid in traversing the linked graph downward: those subgraphs are ignored unless otherwise reachable.

Changing the model object graph

GraphModify2 (base class)

The parent of the requests below, it includes a targetObjects property that specifies from which model objects to start processing. The LegalGraphTargets request can be used to determine which types of model object may be targeted.

The childOptions property lists how to process the contents of targeted objects.

Because these requests change the data stored by the server, a dryRun property is provided that enables attempting to obtain the same response or error without actually making any changes.

ChildOption

By default if a ‘child’ object is contained by a ‘parent’ targeted object then it is processed along with its parent if it is not also contained by another parent object that is not targeted. Use requests’ childOptions property to specify that children should be processed or not regardless of other parents.

The includeType and excludeType properties specify for which types of children to override the behavior. For children that are annotations, the includeNs and excludeNs properties use the annotation namespace to limit the applicability of the override.

Chgrp2

Change the group ID of the targeted objects and their contents. The objects are moved to the group specified by the groupId property.

Chown2

Change the user ID of the targeted objects and their contents. The objects are given to the user specified by the userId property.

Chmod2

Change the permissions for the targeted objects which must be groups. The permissions property specifies the new group type.

Delete2

Delete the targeted objects and their contents. For original file instances the underlying file in the server’s binary repository may be deleted also.

Duplicate

Duplicate a subgraph from the model object graph, starting from the targeted objects and recursing to their contents. The typesToDuplicate, typesToReference, typesToIgnore properties offer control over where in the graph traversal to stop duplicating and with what in the original graph to link the duplicate subgraph.

SkipHead

Defer processing to start only at specific contents of the targeted objects. The startFrom property specifies the types of object to actually target with the processing and the request property, which may be any of the other requests from this section, specifies what to do to those objects once identified.

Command-line interface

OMERO’s command-line interface client includes chgrp, chown, delete plugins that construct the corresponding Chgrp2, Chown2, Delete2 requests. Additionally, the group plugin offers the Chmod2 request and the fs plugin offers the DiskUsage2 request.

Request builders for Java

The Java gateway includes the Requests.java class which offers Java developers a set of builders that use method-chaining to allow convenient construction of new instances of the above requests.