Code organization

[Rylern]

This issue explains how the code of this extension is organized.

Java code

This corresponds to the src/main/java/qupath/ext/omero folder.

OmeroExtension

The OmeroExtension class add actions and menus to the QuPath Extensions menu (see the gui section).

gui

The gui folder contains all UI elements of the extension (and only the UI, see the core section for the core functionalities). Each package of this folder corresponds to an action/menu installed in the Extension menu of QuPath (see the OmeroExtension section).

• The annotationimporter contains an action that imports QuPath annotations from an OMERO server to the currently opened image. Dialogs are used to ask the user for some parameters and show information.
• The annotationsender is the same as annotationimporter, except that it sends annotations from QuPath to an OMERO server.
• The browser folder is used to create a new connection to an OMERO server or browse a connected OMERO server.
  • The BrowseMenu / BrowseMenuModel represents the actual menu. See below for the available options it offers.
  • The newserver folder allows to add a connection to an OMERO server. It simply consists of a dialog.
  • The serverbrowser folder allows to browse a connected OMERO server.
  • The BrowserCommand is the action that starts a browser (see below).
  • The Browser / BrowserModel contains a window allowing the user to browse an OMERO server, get information about OMERO entities and open OMERO images.
  • The advancedinformation folder contains a window that displays detailed information on an OMERO entity. This window can be launched from the browser.
  • The advancedsearch folder contains a window that allows to search for OMERO entities on a server. . It can also be launched from the browser.
  • The hierarchy folder contains classes used by the TreeView of the browser. This treeview shows the projects/datasets/images of a server.
  • The settings folder contains a window that allows to set different settings related to a server.
• The connectionsmanager folder contains UI elements to manage (connect to, disconnect from, remove) a connection to an OMERO server.
  • The ConnectionsManagerCommand is the action that starts the connection manager (see below).
  • The ConnectionsManager / ConnectionsManagerModel provides a window that displays the connections to all servers. The user can connect, log in, log out, and remove a connection to a server.
  • The connection folder contains a UI element used internally by the connection manager.
• The UiUtilities class contains utility functions used by UI elements.

A few things can be added:

• The data that the UI elements show comes from classes of the core folder, so when some data is updated, the changes must be propagated to the UI elements that show it. However, such data can be updated from any thread, and the UI elements can only be updated from the JavaFX thread. This is why some UI classes use a SomeClassModel class. These classes are used to propagate changes of some data from any thread to the JavaFX thread.
• All strings shown to the user are externalized, all UI elements are defined in FXML files, and a CSS stylesheet is used (see the resources section).

imageserver

The imageserver folder contains the ImageServer used by any image opened from an OMERO server and its corresponding ImageServerBuilder. The functionalities of the image server (e.g. reading pixels, getting metadata) are mostly delegated to functions present in the core folder.

When opening an image coming from an OMERO server, a connection is established to the server if it's not already the case.

core

The core folder contains everything else, i.e. the core functionalities of the extension.

• The WebClients class monitors all active connections to OMERO servers. A connection is represented by the WebClient class, described below. WebClients is the class to use when creating a new WebClient or removing an existing one, don't directly use WebClient to add/remove a connection.
• The WebClient class represents a connection to an OMERO server. It handles creating a connection with an OMERO server, logging in, keeping the connection alive, and logging out. It has a reference to a ApisHandler (described below) which can be used to retrieve information from the OMERO server, and a reference to a Server (described below) which is the ancestor of all OMERO entities.
• RequestSender is a utility class that sends web request and can convert HTTP responses to an understandable format (like JSON for example).
• WebUtilities contains utility methods for handling web requests.
• ClientsPreferencesManager is a utility class that handles client information stored in the QuPath preferences.
• The apis folder contains classes that perform requests to the different web APIs.
  • Depending on the request, OMERO requires to use one of the different web APIs (IViewer, JSON, WebClient, or WebGateway API). Each of this API has a corresponding class in this folder to perform operations.
  • The ApisHandler class was created to simplify this use of several APIs. It redirects each web request to the appropriate API contained in this package, so this is the class that should be used outside of this folder. A ApisHandler is not meant to be directly created, but rather accessed through a WebClient (described above).
  • The ApiUtilities class and utilities folder contains utility functions used internally in this package.
  • The authenticator folder contains classes to prompt the user for credentials. A window is used to get the credentials if the graphical user interface is used. Otherwise, the command line is used.
• The pixelapis contains different methods to read the pixel values of an image. As the time of writing, pixels can be accessed through the web API, the ICE API, or the ms pixel buffer API (see the web, ice, and mspixelbuffer folders). Each new method should override the two interfaces present in this package.
  • PixelAPI is an interface that provides information (e.g. types of image supported) on a specific API to access pixel values of an OMERO image. It can also be used to create a PixelAPIReader (described below) corresponding to this API. There is usually one PixelAPI per WebClient.
  • PixelAPIReader is an interface that allows to read pixel values from a tile request. It should only be created by the corresponding PixelAPI. There is one PixelAPIReader per ImageServer, so there can be several PixelAPIReader per WebClient (if multiple images coming from the same server are opened at the same time).
• The entities folder contains classes that represents objects required or returned by functions of the apis folder. They are mainly used to represent data and don't contain much logic except for the repositoryentities folder.
  • The repositoryentities folder contains elements belonging to the OMERO entity hierarchy (server -> orphaned folder / project -> dataset -> image). A Server allows to access all elements of an OMERO server. It can be retrieved through a WebClient.

Miscellaneous

• Every package contains a package-info.java file that explains how the package is organized.
• Each time a function takes some time to complete (for example when making HTTP requests), it is asynchronous using the Java CompletableFuture. The functions are then executed in a random thread.
• HTTP requests use the new Java HTTP client. It natively uses CompletableFutures.
• Unless explicitly written in the documentation, all public functions never return null. When a function is not guaranteed to return a result, the Java Optional API is used or a documented exception is thrown.

Resources

This corresponds to the src/main/resources/qupath/ext/omero folder.

• The styles.css contains the CSS stylesheet of the extension.
• The strings.properties and strings_fr.properties contains all strings shown to the user.
• All other files of this folder are FXML files describing UI elements. All FXML file are located in folders that correspond to their Java controllers.

Tests

This corresponds to the src/test/java/qupath/ext/omero folder. Tests on one class Class are grouped into a TestClass class. Usually, most of the public functions of a class are tested. They are a good way to see how the functions of the extension should be used.

Unit tests

Unit tests have been implemented on functions not requiring access to an OMERO server and not part of the UI. They will always be executed when running tests.

Integration tests

Integration tests have been implemented on classes requiring access to an OMERO server. These classes extend the OmeroServer class which gives access to an OMERO server hosted on a local Docker container. If Docker can't be found on the host machine, all integration tests are skipped.

The TestContainer library is used to communicate with Docker. Three containers are installed:

• A postgres container (needed for the OMERO server).
• A redis container (needed for the OMERO Web server).
• An OMERO.web container (provides the web interface to the OMERO server).
• An OMERO.server container.

A bash script and some files in the src/test/resources/omero-server folder are transferred to the OMERO.server container. They are used to initialize the server with basic data (some datasets, images...). The files in src/test/resources/omero-web are used to initialize the web server (for example by installing the OMERO Pixel Data Microservice on it).

Miscellaneous

• A TestUtilities class contains several utility functions used in tests.

sample-scripts

The sample-scripts folder contains examples of scripts that use several functionalities of this extension.