Add more opts support for getObjects('Annotation')

[will-moore]

This adds support for various options for conn.getObjects("Annotation", opts), in preparation for JSON api:

Tests added in ome/openmicroscopy#6458

Supported opts - All are optional (but parent_ids needs parent_type)

• "parent_type": "dataset"
• "parent_ids": [1, 2]
• "ann_type': "tag"
• "ns": "my.namespace"

E.g. /api/annotations/?type=tag&project=1&project=2 would be backed by:

conn.getObjects("Annotation", opts={
  "ann_type": "tag",
  "parent_type": "project",
  "parent_ids": [1,2]
})

Known issue: Loading Parents

For webclient/api/annotations/ we get the annotations along with links to the parents and the parent objects too.
E.g.

  "link": {
    "id": 39752336,
    "owner": {
      "id": 2
    },
    "parent": {
      "id": 3414011,
      "class": "ImageI",
      "name": "10percent-Wt1-GFP-spheroid-MV.czi [0]"
    },
    "date": "2017-11-27T14:13:19+00:00",
    "permissions": {
      "canDelete": false,
      "canAnnotate": false,
      "canLink": false,
      "canEdit": false
    }
  }

This is useful to have permissions, timestamp, owner etc on the link but it is particularly essential when we are loading annotations on multiple objects. E.g. /api/annotations/?type=tag&project=1&project=2 would load annotations for 2 projects, BUT we without links, we don't know which Annotations are linked to which Project.

But, it doesn't appear possible to achieve this with omero_marshal, since for Annotations, there is no handling of links to Parent objects. Annotations are "Annotatable", so we check for annotations ON the object https://github.com/ome/omero-marshal/blob/f8ff1c2e439f0599d96423b7f64898864548ba9f/omero_marshal/encode/encoders/annotation.py#L68
but not whether the Object (annotation) is annotating a Parent.
In fact, I don't see that it's possible for e.g. an Annotation to have links loaded (in the same way that a Project or Dataset can have obj.copyAnnotationLinks(), since the possible links for an Annotation object are stored in a different Table for each parent, e.g. ProjectAnnotationLinks, DatasetAnnotationLinks etc.

[will-moore]

Tests added in ome/openmicroscopy#6458

[will-moore]

Comment on what changed after first commit....

The problem with the getObjects() is that we can't easily handle OR logic. E.g. "get Annotations with links to Project:1 OR Dataset:2". Currently, for each obj_type we add a clause, so we get AND logic:

                    clauses.append(
                        "exists (from %sAnnotationLink as link "
                        "where link.child.id = obj.id "
                        "and link.parent.id in (:%s_ids))" % (obj_type, plural))
                    params.add("%s_ids" % plural, rlist([rlong(i) for i in ids]))

Therefore,
conn.getObjects("Annotation", opts={"ann_type": "tag", "projects": [1,2], "datasets": [3,4]}) won't give you annotations on all objects, as you currently get with e.g. https://idr.openmicroscopy.org/webclient/api/annotations/?type=map&screen=3&image=3414011

Do we ever need to load annotations for more that 1 type of Object? E.g. webclient almost never allows you to select multiple different Object types, (e.g. Dataset and Image, except maybe in the search results)

The webclient/api endpoint does a series of queries select oal from %sAnnotationLink as oal for each obj_type requested. Each Database query only supports 1 object type. So it's probably OK for the getObjects("Annotation") to also support just ONE parent type. Same behaviour in E.g.

conn.getAnnotationLinks(...parent_type, parent_ids=None)

So, let's instead go for:

conn.getObjects("Annotation", opts={
  "ann_type": "tag",
  "parent_type": "project",
  "parent_ids": [1,2]
})

[knabar]

Do we ever need to load annotations for more that 1 type of Object? E.g. webclient almost never allows you to select multiple different Object types, (e.g. Dataset and Image, except maybe in the search results)

The webclient/api endpoint does a series of queries select oal from %sAnnotationLink as oal for each obj_type requested. Each Database query only supports 1 object type. So it's probably OK for the getObjects("Annotation") to also support just ONE parent type.

It makes sense to me to limit the parent type to one per request, if a client requires annotations on different parent types, the client can make multiple requests.

I think it could even be justified to limit requests to a single parent object if that simplifies the requests and responses significantly.

[knabar]

Similar to parent types, it might be best to stick with the built-in annotation types here. There is only one other reference to ratings in all of OMERO.py, which arguably should not be there either. This would also remove the special treatment of the namespace option in line 5210.

[will-moore]

Done in 367e22e