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).
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.
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 QuPathExtensions
menu (see thegui
section).gui
The
gui
folder contains all UI elements of the extension (and only the UI, see thecore
section for the core functionalities). Each package of this folder corresponds to an action/menu installed in theExtension
menu of QuPath (see theOmeroExtension
section).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.annotationsender
is the same asannotationimporter
, except that it sends annotations from QuPath to an OMERO server.browser
folder is used to create a new connection to an OMERO server or browse a connected OMERO server.BrowseMenu
/BrowseMenuModel
represents the actual menu. See below for the available options it offers.newserver
folder allows to add a connection to an OMERO server. It simply consists of a dialog.serverbrowser
folder allows to browse a connected OMERO server.BrowserCommand
is the action that starts a browser (see below).Browser
/BrowserModel
contains a window allowing the user to browse an OMERO server, get information about OMERO entities and open OMERO images.advancedinformation
folder contains a window that displays detailed information on an OMERO entity. This window can be launched from the browser.advancedsearch
folder contains a window that allows to search for OMERO entities on a server. . It can also be launched from the browser.hierarchy
folder contains classes used by the TreeView of the browser. This treeview shows the projects/datasets/images of a server.settings
folder contains a window that allows to set different settings related to a server.connectionsmanager
folder contains UI elements to manage (connect to, disconnect from, remove) a connection to an OMERO server.ConnectionsManagerCommand
is the action that starts the connection manager (see below).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.connection
folder contains a UI element used internally by the connection manager.UiUtilities
class contains utility functions used by UI elements.A few things can be added:
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 aSomeClassModel
class. These classes are used to propagate changes of some data from any thread to the JavaFX thread.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 thecore
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.WebClients
class monitors all active connections to OMERO servers. A connection is represented by theWebClient
class, described below.WebClients
is the class to use when creating a newWebClient
or removing an existing one, don't directly useWebClient
to add/remove a connection.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 aApisHandler
(described below) which can be used to retrieve information from the OMERO server, and a reference to aServer
(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.apis
folder contains classes that perform requests to the different web APIs.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. AApisHandler
is not meant to be directly created, but rather accessed through aWebClient
(described above).ApiUtilities
class andutilities
folder contains utility functions used internally in this package.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.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 theweb
,ice
, andmspixelbuffer
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 aPixelAPIReader
(described below) corresponding to this API. There is usually onePixelAPI
perWebClient
.PixelAPIReader
is an interface that allows to read pixel values from a tile request. It should only be created by the correspondingPixelAPI
. There is onePixelAPIReader
perImageServer
, so there can be severalPixelAPIReader
perWebClient
(if multiple images coming from the same server are opened at the same time).entities
folder contains classes that represents objects required or returned by functions of theapis
folder. They are mainly used to represent data and don't contain much logic except for therepositoryentities
folder.repositoryentities
folder contains elements belonging to the OMERO entity hierarchy (server -> orphaned folder / project -> dataset -> image). AServer
allows to access all elements of an OMERO server. It can be retrieved through aWebClient
.Miscellaneous
package-info.java
file that explains how the package is organized.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.styles.css
contains the CSS stylesheet of the extension.strings.properties
andstrings_fr.properties
contains all strings shown to the user.Tests
This corresponds to the
src/test/java/qupath/ext/omero
folder. Tests on one classClass
are grouped into aTestClass
class. Usually, most of thepublic
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 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 insrc/test/resources/omero-web
are used to initialize the web server (for example by installing the OMERO Pixel Data Microservice on it).Miscellaneous
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.