Java classes for model graph operations

This description of the roles played by server-side Java classes assumes familiarity with the Model graph operations machinery of OMERO.server.

Traversing and acting

OMERO.server’s GraphTraversal is at the core of all graph operations,

  • querying the database to establish the model graph, with the help of GraphPathBean
  • applying the graph operation’s policy rules and changing the graph node states
  • acting on the model objects according to the final state of the graph.

GraphTraversal’s Processor interface is implemented by specific graph requests to act on the selected model objects. GraphTraversal implements its PlanExecutor interface with code that calls those Processor methods: it provides that PlanExecutor implementation back to requests so that they can control exactly if or when to act via their Processor implementation.

ModelObjectSequencer ensures that objects are acted upon in the proper order. For example, in deleting OriginalFile instances, a directory’s contents are deleted before their containing directory is deleted.

In OMERO.blitz, BaseGraphTraversalProcessor offers a useful base class for implementing Processor and NullGraphTraversalProcessor has no effects at all. Several graph requests define their own InternalProcessor class.

Policy rules for node transitions

GraphTraversal manages the traversal of the model graph but it is instances of OMERO.server’s GraphPolicy that decide how the graph’s nodes are to change state during traversal. The class is instantiated by the static parseRules method of GraphPolicyRule which provides a GraphPolicy based on parsing a sequence of GraphPolicyRule instances. Each of those rules describes in textual form how it matches graph fragments and what to do in the event of a match.

OMERO.blitz’s BaseGraphPolicyAdjuster provides convenient hooks for adjusting how an existing GraphPolicy transitions nodes. Classes that do such adjustment include,

ChildOptionsPolicy
marks certain nodes as IS_LAST or IS_NOT_LAST once they are RELEVANT
SkipHeadPolicy
  1. in skipping the head, prevents traversal beyond certain node types
  2. in processing the remaining graph, preserves permissions overrides established in the first phase
SkipTailPolicy
prevents traversal beyond certain node types

OMERO.server provides the GraphPolicyRulePredicate interface which is used for the ; suffix notation in rule matches. For example, GroupPredicate can match group=system and PermissionsPredicate can match perms=r?ra??.

OMERO.blitz graph requests

The Graph requests of OMERO.blitz benefit from helper classes. GraphRequestFactory instantiates the graph request implementations and provides them means to create a context-aware GraphHelper. This helper includes the code that is common to many of the graph requests. Helper methods not requiring any context are instead collected in the stateless GraphUtil.