<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Model graph operations — OMERO documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<!--[if lt IE 9]>
<script src="../../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js"></script>
<script src="../../_static/jquery.js"></script>
<script src="../../_static/underscore.js"></script>
<script src="../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="../../_static/doctools.js"></script>
<script src="../../_static/sphinx_highlight.js"></script>
<script src="../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Java classes for model graph operations" href="GraphsImpl.html" />
<link rel="prev" title="The server’s view of administrator restrictions" href="LightAdmins.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../index.html" class="icon icon-home"> OMERO
</a>
<div class="version">
5.6
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../users/index.html">OMERO Overview and CLI User Documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../sysadmins/index.html">System Administrator Documentation</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">Developer Documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../index.html#introduction-to-omero">Introduction to OMERO</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#using-the-omero-api">Using the OMERO API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#analysis">Analysis</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#scripts-plugins-for-omero">Scripts - plugins for OMERO</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#web">Web</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#insight">Insight</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#more-on-api-usage">More on API Usage</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#the-ome-data-model">The OME Data Model</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#searching">Searching</a></li>
<li class="toctree-l2"><a class="reference internal" href="../index.html#authentication-and-security">Authentication and Security</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html#omero-server-in-depth">OMERO.server in depth</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../Server.html">OMERO.server overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="ExtendingOmero.html">Extending OMERO.server</a></li>
<li class="toctree-l3"><a class="reference internal" href="../server-blitz.html">OMERO.blitz</a></li>
<li class="toctree-l3"><a class="reference internal" href="FS.html">OMERO.fs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ImportFS.html">Import under OMERO.fs</a></li>
<li class="toctree-l3"><a class="reference internal" href="../server-processor.html">OMERO.processor</a></li>
<li class="toctree-l3"><a class="reference internal" href="../server-rendering.html">OMERO.server image rendering</a></li>
<li class="toctree-l3"><a class="reference internal" href="Clustering.html">Clustering</a></li>
<li class="toctree-l3"><a class="reference internal" href="CollectionCounts.html">Collection counts</a></li>
<li class="toctree-l3"><a class="reference internal" href="HowToCreateAService.html">How To create a service</a></li>
<li class="toctree-l3"><a class="reference internal" href="Sessions.html">OMERO sessions</a></li>
<li class="toctree-l3"><a class="reference internal" href="Aop.html">Aspect-oriented programming</a></li>
<li class="toctree-l3"><a class="reference internal" href="Context.html">OmeroContext</a></li>
<li class="toctree-l3"><a class="reference internal" href="Events.html">OMERO events and provenance</a></li>
<li class="toctree-l3"><a class="reference internal" href="Properties.html">Properties</a></li>
<li class="toctree-l3"><a class="reference internal" href="Queries.html">Using server queries internally</a></li>
<li class="toctree-l3"><a class="reference internal" href="Throttling.html">OMERO throttling</a></li>
<li class="toctree-l3"><a class="reference internal" href="RenderingEngine.html">OMERO rendering engine</a></li>
<li class="toctree-l3"><a class="reference internal" href="ScalingOmero.html">Scaling Omero</a></li>
<li class="toctree-l3"><a class="reference internal" href="SqlAction.html">SqlAction</a></li>
<li class="toctree-l3"><a class="reference internal" href="LightAdmins.html">The server’s view of administrator restrictions</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Model graph operations</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#motivation">Motivation</a></li>
<li class="toctree-l4"><a class="reference internal" href="#approach">Approach</a></li>
<li class="toctree-l4"><a class="reference internal" href="#configuration">Configuration</a></li>
<li class="toctree-l4"><a class="reference internal" href="#logging">Logging</a></li>
<li class="toctree-l4"><a class="reference internal" href="#encouragement">Encouragement</a></li>
<li class="toctree-l4"><a class="reference internal" href="#options">Options</a></li>
<li class="toctree-l4"><a class="reference internal" href="#skiphead">SkipHead</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="GraphsImpl.html">Java classes for model graph operations</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">OMERO</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html" class="icon icon-home"></a></li>
<li class="breadcrumb-item"><a href="../index.html">Developer Documentation</a></li>
<li class="breadcrumb-item active">Model graph operations</li>
<li class="wy-breadcrumbs-aside">
<a href="../../_sources/developers/Server/ObjectGraphs.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="model-graph-operations">
<h1>Model graph operations<a class="headerlink" href="#model-graph-operations" title="Permalink to this heading">ïƒ</a></h1>
<div class="topic">
<p class="topic-title">Overview</p>
<p>When the OMERO server acts on its model objects it must determine the
impact on related objects. For instance, deleting an image may entail
deleting users’ rendering settings for that image, also the links to
any datasets that the image is in. Understanding the details of the
implementation substantially assists in debugging or creating server
operations that act on the directed graph of model objects.</p>
</div>
<section id="motivation">
<h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this heading">ïƒ</a></h2>
<p>The OMERO model objects are interlinked. Plates may have wells whose
samples come from multiple runs. Both datasets and well samples may have
images, but in different ways. Datasets, wells, images, among others,
may all be annotated. Images themselves are not simple: for example,
they may be in a fileset, they may have ROIs drawn on them, they may
share an instrument with the projection of that image. All these
entities are separate objects that can be thought of as forming the
nodes (vertices) of a directed graph of relationships.</p>
<p>Various operations supported by the OMERO server, most commonly moving
objects to a different group, or deleting them, may implicitly include
many related objects. For example, if one deletes a fileset, one also
deletes the images from that fileset, and even the comments on those
images. This section describes how the graph of model objects is
traversed and how the target set of related objects is determined.</p>
<p>This technical detail is important to understand if one wishes to,</p>
<ul class="simple">
<li><p>adjust the set of related model objects that are included in
operations</p></li>
<li><p>change the types of <a class="reference internal" href="../Model.html"><span class="doc">OME-Remote Objects</span></a> model objects or the permissible
links among them</p></li>
<li><p>fix bugs in the related request objects defined in <a class="reference external" href="https://github.com/ome/omero-blitz/blob/v5.8.0/src/main/slice/omero/cmd/Graphs.ice">Graphs.ice</a> that may be
submitted to <a class="reference internal" href="Sessions.html"><span class="doc">OMERO sessions</span></a> for execution.</p></li>
</ul>
</section>
<section id="approach">
<h2>Approach<a class="headerlink" href="#approach" title="Permalink to this heading">ïƒ</a></h2>
<section id="graph-node-states-and-transitions">
<h3>Graph node states and transitions<a class="headerlink" href="#graph-node-states-and-transitions" title="Permalink to this heading">ïƒ</a></h3>
<p>In determining which model objects to process, and how, each
corresponding graph node is in one of these states:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 21%" />
<col style="width: 23%" />
<col style="width: 23%" />
<col style="width: 32%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>adjective</p></th>
<th class="head"><p>rule format</p></th>
<th class="head"><p>Action enum</p></th>
<th class="head"><p>Orphan enum</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>irrelevant</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">[E]{i}</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">EXCLUDE</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">IRRELEVANT</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>relevant</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">[E]{r}</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">EXCLUDE</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">RELEVANT</span></code></p></td>
</tr>
<tr class="row-even"><td><p>orphaned</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">[E]{o}</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">EXCLUDE</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">IS_LAST</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>attached</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">[E]{a}</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">EXCLUDE</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">IS_NOT_LAST</span></code></p></td>
</tr>
<tr class="row-even"><td><p>to delete</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">[D]</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">DELETE</span></code></p></td>
<td><p>n/a</p></td>
</tr>
<tr class="row-odd"><td><p>to include</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">[I]</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">INCLUDE</span></code></p></td>
<td><p>n/a</p></td>
</tr>
<tr class="row-even"><td><p>outside</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">[O]</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">OUTSIDE</span></code></p></td>
<td><p>n/a</p></td>
</tr>
</tbody>
</table>
<p>“enum†refers to the enumerations defined in <a class="reference external" href="https://github.com/ome/omero-server/blob/v5.7.0/src/main/java/ome/services/graphs/GraphPolicy.java">GraphPolicy.java</a>. Note also
that, as for the introduction to <a class="reference internal" href="../Modules/Delete.html"><span class="doc">Deleting in OMERO</span></a>, “links†are
simply edges in the graph, distinct from the classes implementing
<a class="reference external" href="https://github.com/ome/omero-model/blob/v5.7.0/src/main/java/ome/model/ILink.java">ILink.java</a> which
themselves have several links, not least to their parent and child
objects.</p>
<p>When traversal begins, the target objects are to be <em>included</em> (e.g.,
for <a class="reference external" href="https://docs.openmicroscopy.org/omero-blitz/5.8.0/slice2html/omero/cmd/Chgrp2.html">Chgrp2</a>) or <em>deleted</em>
(e.g., for <a class="reference external" href="https://docs.openmicroscopy.org/omero-blitz/5.8.0/slice2html/omero/cmd/Delete2.html">Delete2</a>) and
other objects are <em>irrelevant</em>.</p>
<p>A list of transition rules is associated with the requested operation.
Each of the target objects is examined in turn and the rules matched
against the state of that object and of those directly linked to it in
either direction. If a rule matches, it may either abort the operation
with an error condition or, more usually, change the state of any of the
objects it matches. Changed objects are themselves queued for
examination and rule matching. The traversal is complete when all queued
objects have been examined with no further transition rule matches.
Rules that can abort the operation are checked only after the other
rules have completed processing. <a class="reference external" href="https://github.com/ome/omero-server/blob/v5.7.0/src/main/java/ome/services/graphs/GraphTraversal.java">GraphTraversal.java</a>’s
<code class="docutils literal notranslate"><span class="pre">planOperation</span></code> method is at the heart of this matching process.</p>
</section>
<section id="further-graph-node-states">
<h3>Further graph node states<a class="headerlink" href="#further-graph-node-states" title="Permalink to this heading">ïƒ</a></h3>
<p>Usual behavior is for <em>orphaned</em> objects related to the target objects
to be included in the operation, but not the otherwise-<em>attached</em>
objects, the non-orphans who have <em>excluded</em> parents that are to be
neither deleted nor included. The related children that may be orphans
are exactly those identified as being <em>relevant</em>. Transition rules match
these against excluded parents to discover if the relevant objects do
have any qualifying parents, changing them to be attached objects. If no
further rules match and some objects remain as relevant, then they are
automatically changed to orphans and examined for further rule matches.
After that processing completes, attached objects are changed back to
being relevant to confirm that excluded qualifying parents still exist
to change them to being attached: this is necessary in case, after an
object was considered attached, other rules changed all those qualifying
parents from being excluded so that the object is now an orphan.</p>
<p>Objects that are changed to be <em>outside</em> are effectively rendered
invisible, outside consideration in the execution phase. In the
execution of an operation the graph traversal code removes links between
included and excluded objects, but it allows links to remain between
outside objects and other objects. Outside objects typically implement
<a class="reference external" href="https://github.com/ome/omero-model/blob/v5.7.0/src/main/java/ome/model/IGlobal.java">IGlobal.java</a> and
have no owner or group.</p>
<p>An additional aspect of objects’ state is if permissions are to be
checked for them. For instance, typically I may move only my own objects
to a different group, but if another user tags my image with my tag,
then I may still move my image and tag to a different group, also moving
that link even though it is not my own object: in that case, permissions
checking is disabled for that <code class="docutils literal notranslate"><span class="pre">ImageAnnotationLink</span></code>. All objects
initially have permissions checking enabled, but the consequence of a
rule may be to disable permissions checking, and if an object with
permissions checking disabled matches a further rule, the objects
changed by that rule also have permissions checking disabled.</p>
</section>
</section>
<section id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this heading">ïƒ</a></h2>
<section id="defining-the-model-graph-transition-rules">
<h3>Defining the model graph transition rules<a class="headerlink" href="#defining-the-model-graph-transition-rules" title="Permalink to this heading">ïƒ</a></h3>
<p>To reduce its complexity, <a class="reference external" href="https://github.com/ome/omero-server/blob/v5.7.0/src/main/java/ome/services/graphs/GraphTraversal.java">GraphTraversal.java</a> does
not include specific detail of how to traverse the graph of
<a class="reference internal" href="../Model.html"><span class="doc">OME-Remote Objects</span></a> model objects. Instead, subclasses of
<a class="reference external" href="https://github.com/ome/omero-server/blob/v5.7.0/src/main/java/ome/services/graphs/GraphPolicy.java">GraphPolicy.java</a> guide the
traversal of the model object graph, configured by
<a class="reference external" href="https://github.com/ome/omero-blitz/blob/v5.8.0/src/main/resources/ome/services/blitz-graph-rules.xml">blitz-graph-rules.xml</a> which
names and defines the lists of transition rules. The named lists of
rules are associated with request object classes by the definition of
the <code class="docutils literal notranslate"><span class="pre">graphRequestFactory</span></code> bean in
<a class="reference external" href="https://github.com/ome/omero-blitz/blob/v5.8.0/src/main/resources/ome/services/blitz-servantDefinitions.xml">blitz-servantDefinitions.xml</a>,
which also specifies which model object properties may never be set to
<code class="docutils literal notranslate"><span class="pre">null</span></code> in executing any requested operation.</p>
<p><a class="reference external" href="https://github.com/ome/omero-blitz/blob/v5.8.0/src/main/resources/ome/services/blitz-graph-rules.xml">blitz-graph-rules.xml</a> begins
with a comment that provides a key to the notation used for transition
rules. The rules name and match model objects based on the state of the
graph nodes, the types of the corresponding objects, the permissions the
user has on those objects, and the names of the properties linking the
objects. To illustrate this, the following sections briefly describe
some different kinds of rule from the <code class="docutils literal notranslate"><span class="pre">deleteRules</span></code> list.</p>
</section>
<section id="propagating-deletion">
<h3>Propagating deletion<a class="headerlink" href="#propagating-deletion" title="Permalink to this heading">ïƒ</a></h3>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="L:ILink.parent<span class="w"> </span>=<span class="w"> </span>[D],<span class="w"> </span>L.child<span class="w"> </span>=<span class="w"> </span>C:[E]{o}/d"
p:changes="C:[D]"
</pre></div>
</div>
<p>If an <code class="docutils literal notranslate"><span class="pre">ILink</span></code>’s parent (e.g., a dataset) is to be deleted, and its
child (e.g., an image) is orphaned and deletable by the user, then
delete the child also.</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="PlateAcquisition[D].wellSample<span class="w"> </span>=<span class="w"> </span>WS:WellSample[E]"
p:changes="WS:[D]"
</pre></div>
</div>
<p>If a plate acquisition (run) is to be deleted, also delete its well
samples (fields).</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="Fileset[D]<span class="w"> </span>=<span class="w"> </span>I:Image[E].fileset"
p:changes="I:[D]"
</pre></div>
</div>
<p>If a fileset is to be deleted, then also delete its images.</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="T:Thumbnail[E].pixels<span class="w"> </span>=/!o<span class="w"> </span>[D]"
p:changes="T:[D]/n"
</pre></div>
</div>
<p>If the pixels of a thumbnail are to be deleted, and are owned by a
different user, then delete the thumbnail regardless of permissions on
it.</p>
</section>
<section id="curtailing-deletion">
<h3>Curtailing deletion<a class="headerlink" href="#curtailing-deletion" title="Permalink to this heading">ïƒ</a></h3>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="Well[D].plate<span class="w"> </span>=<span class="w"> </span>C:[E]{!a}"
p:changes="C:{a}"
</pre></div>
</div>
<p>If a well is to be deleted but its plate is excluded and not attached,
regard the plate as attached.</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="C:Channel[E]{r}.pixels<span class="w"> </span>=<span class="w"> </span>Pixels[E]{i}"
p:changes="C:{a}"
</pre></div>
</div>
<p>If an irrelevant pixels object has a relevant channel, then regard the
channel as attached.</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="Pixels[D].relatedTo<span class="w"> </span>=<span class="w"> </span>P:[E]{!a}"
p:changes="P:{a}"
</pre></div>
</div>
<p>If a pixels object is to be deleted, regard any related, excluded pixels
objects as attached. Because the pixels of an image are related to the
pixels of a projection of that image, this rule prevents the deletion of
an image from causing inadvertent deletion of the image’s projections.</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="L:ILink[!D].parent<span class="w"> </span>=<span class="w"> </span>[E]/d,<span class="w"> </span>L.child<span class="w"> </span>=<span class="w"> </span>C:[E]{r}"
p:changes="C:{a}"
</pre></div>
</div>
<p>If an <code class="docutils literal notranslate"><span class="pre">ILink</span></code> that is not to be deleted itself has a deletable,
excluded parent and a relevant child, regard that child as attached.</p>
</section>
<section id="other-kinds-of-transition-rule">
<h3>Other kinds of transition rule<a class="headerlink" href="#other-kinds-of-transition-rule" title="Permalink to this heading">ïƒ</a></h3>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="E:IEnum[E]"
p:changes="E:[O]"
</pre></div>
</div>
<p>Regard excluded <code class="docutils literal notranslate"><span class="pre">IEnum</span></code> objects as being outside the operation. (Rules
do not need to match on links among multiple objects.)</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="F:Fileset[!D].images<span class="w"> </span>=<span class="w"> </span>[D],<span class="w"> </span>F.images<span class="w"> </span>=<span class="w"> </span>[!D]"
p:error="may<span class="w"> </span>not<span class="w"> </span>split<span class="w"> </span>{F}"
</pre></div>
</div>
<p>Throw an error if a fileset that is not to be deleted includes an image
that is to be deleted and an image that is not to be deleted.</p>
<p>In reviewing the <code class="docutils literal notranslate"><span class="pre">chgrpRules</span></code> list, one sees conditions that require
matching <code class="docutils literal notranslate"><span class="pre">$to_private</span></code> or <code class="docutils literal notranslate"><span class="pre">!$to_private</span></code>. A request, in this case
<a class="reference external" href="https://github.com/ome/omero-blitz/blob/v5.8.0/src/main/java/omero/cmd/graphs/Chgrp2I.java">Chgrp2I.java</a>, may set arbitrary
conditions upon which rules may be predicated. The <code class="docutils literal notranslate"><span class="pre">to_private</span></code>
condition, or its absence, is used to cause different behavior when the
objects are being moved into a private group.</p>
</section>
</section>
<section id="logging">
<h2>Logging<a class="headerlink" href="#logging" title="Permalink to this heading">ïƒ</a></h2>
<section id="changing-the-log-level">
<h3>Changing the log level<a class="headerlink" href="#changing-the-log-level" title="Permalink to this heading">ïƒ</a></h3>
<p>It is informative to observe the sequence of rule applications as the
graph is traversed and decisions about model objects are made. To do so
requires configuring <a class="reference internal" href="../logging.html"><span class="doc">Omero logging</span></a> for the server, specifically
<a class="reference external" href="https://github.com/ome/openmicroscopy/blob/develop/etc/logback.xml">https://github.com/ome/openmicroscopy/blob/develop/etc/logback.xml</a>. To activate graph traversal debug logging,
adjust the ends of the lines,</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><logger</span><span class="w"> </span><span class="na">name=</span><span class="s">"omero.cmd.graphs"</span><span class="w"> </span><span class="na">level=</span><span class="s">"INFO"</span><span class="nt">/></span>
<span class="nt"><logger</span><span class="w"> </span><span class="na">name=</span><span class="s">"ome.services.graphs"</span><span class="w"> </span><span class="na">level=</span><span class="s">"INFO"</span><span class="nt">/></span>
</pre></div>
</div>
<p>such that they instead read,</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span><span class="nt"><logger</span><span class="w"> </span><span class="na">name=</span><span class="s">"omero.cmd.graphs"</span><span class="w"> </span><span class="na">level=</span><span class="s">"DEBUG"</span><span class="nt">/></span>
<span class="nt"><logger</span><span class="w"> </span><span class="na">name=</span><span class="s">"ome.services.graphs"</span><span class="w"> </span><span class="na">level=</span><span class="s">"DEBUG"</span><span class="nt">/></span>
</pre></div>
</div>
<p>The resulting extra information in <code class="file docutils literal notranslate"><span class="pre">var/log/Blitz-0.log</span></code> is of
particular assistance in debugging: it pinpoints the rule applications
that caused incorrect determinations of what action to take with model
objects. Note that a <code class="docutils literal notranslate"><span class="pre">*</span></code> suffix on a model object referenced in the
logs indicates that permissions are not to be checked for it.</p>
</section>
<section id="expanding-the-reports-of-transition-rule-matches">
<h3>Expanding the reports of transition rule matches<a class="headerlink" href="#expanding-the-reports-of-transition-rule-matches" title="Permalink to this heading">ïƒ</a></h3>
<p>In the previous section, it can be seen that model objects that match
rule conditions may be named. For example, in,</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="Fileset[D]<span class="w"> </span>=<span class="w"> </span>I:Image[E].fileset"
p:changes="I:[D]"
</pre></div>
</div>
<p>the image is named <code class="docutils literal notranslate"><span class="pre">I</span></code>. When a rule matches, the debug logging reports
which model object matched each name. If it remains unclear why a rule
matched, further objects may be named. For example, changing the first
line to name the fileset,</p>
<div class="highlight-xml notranslate"><div class="highlight"><pre><span></span>p:matches="F:Fileset[D]<span class="w"> </span>=<span class="w"> </span>I:Image[E].fileset"
</pre></div>
</div>
<p>would also report in the log which fileset matched the rule.</p>
</section>
</section>
<section id="encouragement">
<h2>Encouragement<a class="headerlink" href="#encouragement" title="Permalink to this heading">ïƒ</a></h2>
<p>On first reading, the above may feel daunting. If model object graph
traversal is not working as desired, thus requires adjustment, review of
debug logs from <code class="file docutils literal notranslate"><span class="pre">var/log/Blitz-0.log</span></code> typically pinpoints the
cause and a minor adjustment to <a class="reference external" href="https://github.com/ome/omero-blitz/blob/v5.8.0/src/main/resources/ome/services/blitz-graph-rules.xml">blitz-graph-rules.xml</a> often
suffices as the fix, with integration tests providing reassurance that
the adjustment was acceptable. Sometimes it can take time and thought to
devise that fix, but one can expect small changes to suffice to fix most
bugs. In getting this new graph traversal implementation to initially
pass integration testing, no test failures required a substantial
rethink of the basic approach and <a class="reference external" href="https://github.com/ome/omero-server/blob/v5.7.0/src/main/java/ome/services/graphs/GraphTraversal.java">GraphTraversal.java</a> itself
did not require a significant rewrite.</p>
<p>The actual lists of transition rules arose in part as a way to achieve
the desired behavior and are not yet as simple and comprehensive as they
could be. While they necessarily reflect the inherent complexity of the
object model of <a class="reference internal" href="../Model.html"><span class="doc">OME-Remote Objects</span></a>, there is potential for reviewing the
rule lists and, perhaps with some additional marker interfaces, making
them more succinct and regular. Incremental movements toward this goal
are worth pursuing.</p>
</section>
<section id="options">
<h2>Options<a class="headerlink" href="#options" title="Permalink to this heading">ïƒ</a></h2>
<p>Every one of the request object classes introduced in the new
implementation of graph traversal is a derived class of
<a class="reference external" href="https://docs.openmicroscopy.org/omero-blitz/5.8.0/slice2html/omero/cmd/GraphModify2.html">GraphModify2</a> and
inherits data members that configure its operation. Each request may
define additional data members for options specific to it, for instance
<a class="reference external" href="https://docs.openmicroscopy.org/omero-blitz/5.8.0/slice2html/omero/cmd/Chgrp2.html">Chgrp2</a> requires the ID of
the target group to be specified. The data members offered by all of the
new requests are,</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">targetObjects</span></code></dt><dd><p>specifies which model objects the operation is to target</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">childOptions</span></code></dt><dd><p>specifies types of model objects (and, for annotations, namespaces)
that should always or never be included in the operation (i.e. always
considered to be orphans, or attached, regardless of excluded parents)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dryRun</span></code></dt><dd><p>specifies if the request is to determine which model objects would be
included in and deleted by the operation, without actually executing
the operation.</p>
</dd>
</dl>
</section>
<section id="skiphead">
<h2>SkipHead<a class="headerlink" href="#skiphead" title="Permalink to this heading">ïƒ</a></h2>
<p>The <a class="reference external" href="https://docs.openmicroscopy.org/omero-blitz/5.8.0/slice2html/omero/cmd/SkipHead.html">SkipHead</a> request
allows specification of the target objects with reference to a common
parent. It wraps an inner <code class="docutils literal notranslate"><span class="pre">request</span></code> data member that starts acting
only after graph traversal reaches types listed in <code class="docutils literal notranslate"><span class="pre">startFrom</span></code>. For
example, to target the images of a specific plate, give the plate in
<code class="docutils literal notranslate"><span class="pre">targetObjects</span></code> and name <code class="docutils literal notranslate"><span class="pre">Image</span></code> in <code class="docutils literal notranslate"><span class="pre">startFrom</span></code>.</p>
<p>This feature is achieved by running the initial request with <code class="docutils literal notranslate"><span class="pre">dryRun</span></code>
set to <code class="docutils literal notranslate"><span class="pre">true</span></code> and the graph traversal policy modified so as to not
examine included nodes of types listed in <code class="docutils literal notranslate"><span class="pre">startFrom</span></code>. A subsequent
request then runs, targeting the <code class="docutils literal notranslate"><span class="pre">startFrom</span></code> model objects that were
included in the first request.</p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="LightAdmins.html" class="btn btn-neutral float-left" title="The server’s view of administrator restrictions" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="GraphsImpl.html" class="btn btn-neutral float-right" title="Java classes for model graph operations" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2000-2025, The Open Microscopy Environment.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>