Skip to content

Code organization

Jump to bottom
Léo Leplat edited this page May 31, 2024 · 1 revision

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

Java code

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

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.

  • The OmeroExtension class add actions and menus to the QuPath Extensions menu.
  • The UiUtilities class contains utility functions used by UI elements.
  • The datatransporters package provides menus and UI elements to send/import annotations, image settings, and key value pairs of the current image to/from the corresponding OMERO server.
    • Each menu is represented by the DataTransporterMenu class.
    • A menu contains items represented by the DataTransporter interface.
  • The browser package 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.

A few things can be added:

  • 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).

core

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

  • 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 other functions present in the core folder.
  • 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 and keeping the connection alive. 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 and screen/plate/well). 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).

By default, a new local OMERO server will be created each time this command is run. As it takes a few minutes, you can instead create a local OMERO server by running the qupath-extension-omero/src/test/resources/server.sh script and setting the OmeroServer.IS_LOCAL_OMERO_SERVER_RUNNING variable to true (qupath-extension-omero/src/test/java/qupath/ext/omero/OmeroServer file). That way, unit tests will use the existing OMERO server instead of creating a new one.

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.

Clone this wiki locally