Java wrapper library

Development
#1

Hi!

Last year, we started working on a small Java wrapper library to reduce code duplication when fetching/storing data on OMERO from different projects (including a Fiji plugin, hence the “ImagePlus” method which should be moved to a child project probably).

For now, this mostly handles projects, datasets, images, pixels, ROIs, tags, key/value pairs, tables and annotation files, but some basic features might still be missing (like renaming an image, strangely enough, retrieving an annotation file or getting the channel colors). Also, I tried to restructure it a bit, but my UML/designing skills are beyond rusty so I’m not sure how it looks…

Is this relevant, or did I miss something easier to use than the raw Java Gateway API (which provides everything, but requires a bit of experience as it does not always return what we expect)?

Also, I was wondering if someone may have recommendations about what would be the best way to handle versioning.
For now, we use the first two digits of the Gateway API version and increment the third, but that does not necessarily reflect the big changes in the wrapper API (which has been quite unstable lately as I refactored everything). But maybe it can be done in a better way?

#2

Hi Pierre,

great work :+1: Yes, from our side the Java Gateway is still the “easiest” way to work with the Java API. I’m also not aware of other general OMERO Java Wrapper projects from the community. Please also feel free to open issues or - even better - PRs against the Java Gateway, when you spot potential improvements.

With respect to versioning: I wouldn’t try to keep it in sync with the gateway version. As you said the versioning should reflect your library’s progress and not some dependencies version. The gateway version also doesn’t really matter that much, as you want compatibility with the server in the end. And as all components are now decoupled, the gateway version does not have to match the OMERO server version (but generally speaking you’re fine if the server and the gateway version is >= 5.5, see for example isCompatibleVersion() method in the Java Gateway).
We have a similar case with the R wrapper which uses the Java gateway. It has it’s own version, but for server versions < 5.5 we have to keep a kind of version compatibility table: OMERO R Gateway .

Kind Regards,
Dominik

#3

Hi Dominik,

I’ll try to find again what was not working as expected. From memory, I think I was told that most methods which return a (raw?) Set (like DatasetData::getImages()) don’t return what’s expected for example. Also, the BrowseFacility::findObject() only returns an incomplete object (without links), unlike getProjects().
The aim of our wrapper was mainly to "factorize code (pixels retrieval) and “simplify” the API (easy tag/table/KV management), but maybe we should try to contribute somehow, if possible.

I won’t be able to work on it for the next 10 days, but I’ll try to open issues and/or PRs as soon as I can.
Also, as suggested, we used omero-test-infra for our tests: shouldn’t the Java API use it too? Would it make sense to write such tests for it, or would it be useless?

#4

Indeed, often it’s not really clear if a method returns a shallow or a fully initialized object. As short term improvement we could certainly improve the documentation. And in the longer run add methods with better names and deprecate the previous ones, and/or add options to specify the “initialization depth”.

In general it’s definitely recommended to use omero-test-infra! The reason we don’t do that for the Java gateway is simply that we’ve not migrated the integration tests from the previous repository OmeroJava yet. Some tests were also running too long for Travis, but with github actions we should look into finally moving the integration tests over into the Java Gateway repository.

Regards,
Dominik