Difference between revisions of "SciJava Common"

(Add infobox)
(Add link to API version history)
 
(15 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Infobox
+
{{ComponentStats:org.scijava:scijava-common}}SciJava Common is a common library for [[SciJava]] software. It provides a plugin framework, with an extensible mechanism for service discovery, backed by its own annotation processor, so that plugins can be loaded dynamically. It is used by both [[ImageJ]] and [[SCIFIO]].
| name                  = SciJava Common
 
| software              = SciJava
 
| logo                  = [[File:scijava-logo.png|128px]]
 
| author                = [https://github.com/orgs/scijava/people SciJava developers]
 
| maintainer            = [[User:Rueden|Curtis Rueden]]<br>[[User:Schindelin|Johannes Schindelin]]<br>[[User:Hinerm|Mark Hiner]]
 
| source                = {{GitHub | org = scijava | repo = scijava-common}}
 
| status                = active
 
| category              =
 
}}SciJava Common is a common library for [[SciJava]] software. It provides a plugin framework, with an extensible mechanism for service discovery, backed by its own annotation processor, so that plugins can be loaded dynamically. It is used by both [[ImageJ]] and [[SCIFIO]].
 
  
 
= Plugin framework =
 
= Plugin framework =
Line 16: Line 7:
 
== Plugin discovery ==
 
== Plugin discovery ==
  
All plugins available on Java's classpath are automatically discovered and made available. This is accomplished by scanning classpath resources for the file path <code>META-INF/json/org.scijava.plugin.Plugin</code>. Such files are generated at compile time by a Java annotation processor that writes them in response to <code>@Plugin</code> annotations on Java classes, an idea inspired by the [https://sezpoz.java.net/ SezPoz] project.
+
All plugins available on Java's classpath are automatically discovered and made available. This is accomplished by scanning classpath resources for the file path <code>META-INF/json/org.scijava.plugin.Plugin</code>. Such files are generated at compile time by a Java annotation processor that writes them in response to <code>@Plugin</code> annotations on Java classes, an idea inspired by the [https://github.com/jglick/sezpoz/ SezPoz] project.
  
 
= Application container =
 
= Application container =
Line 24: Line 15:
 
== Services ==
 
== Services ==
  
{{Sidebox | title = Comparison with ImageJ 1.x
+
{{ImageJ1
| text = Whereas [[ImageJ1]] is a [https://en.wikipedia.org/wiki/Singleton_pattern singleton], with static methods to access much of its functionality, [[ImageJ2]] encapsulates its program state in the application context, allowing multiple simultaneous such contexts in the same JVM.
+
| Whereas [[ImageJ1]] is a [[wikipedia:Singleton pattern|singleton]], with static methods to access much of its functionality, [[ImageJ2]] encapsulates its program state in the application context, allowing multiple simultaneous such contexts in the same JVM.
}}
+
}}ImageJ encapsulates its various parts as separate "services" that provide related state functionality and track related program state. An instance of the {{Javadoc | package = net/imagej | class = ImageJ}} class is nothing more than a collection of these services; this instance is referred to as the "application gateway." Services are defined as interfaces, with concrete implementations as plugins. This design provides [http://c2.com/cgi/wiki?SoftwareSeam seams] in the right places so that behavior at every level can be customized and overridden.
ImageJ encapsulates its various parts as separate "services" that provide related state functionality and track related program state. An instance of the {{Javadoc | package = net/imagej | class = ImageJ}} class is nothing more than a collection of these services; this instance is referred to as the "application gateway." Services are defined as interfaces, with concrete implementations as plugins. This design provides [http://c2.com/cgi/wiki?SoftwareSeam seams] in the right places so that behavior at every level can be customized and overridden.
 
  
 
=== SciJava services ===
 
=== SciJava services ===
Line 33: Line 23:
 
Here are a few of SciJava Common's major core services:
 
Here are a few of SciJava Common's major core services:
  
* '''{{Javadoc | package = org/scijava/app | class = AppService}}''' - Tracks software applications (SCIFIO, ImageJ, etc.) present in the context.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/app | class = AppService}}''' - Tracks software applications (SCIFIO, ImageJ, etc.) present in the context.
* '''{{Javadoc | package = org/scijava/display | class = DisplayService}}''' - Tracks available displays, as well as the active display, and provides the means to create new displays to visualize data.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/display | class = DisplayService}}''' - Tracks available displays, as well as the active display, and provides the means to create new displays to visualize data.
* '''{{Javadoc | package = org/scijava/event | class = EventService}}''' - Publishes events to the [https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern event bus], and allows interested parties to subscribe to them. The service provides the central means of communication between various parts of the codebase.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/event | class = EventService}}''' - Publishes events to the [[wikipedia:Publish%E2%80%93subscribe pattern|event bus]], and allows interested parties to subscribe to them. The service provides the central means of communication between various parts of the codebase.
* '''{{Javadoc | package = org/scijava/io | class = IOService}}''' - General tools for opening and saving data within the context.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/io | class = IOService}}''' - General tools for opening and saving data within the context.
* '''{{Javadoc | package = org/scijava/menu | class = MenuService}}''' - Builds the application menu structure.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/menu | class = MenuService}}''' - Builds the application menu structure.
* '''{{Javadoc | package = org/scijava/module | class = ModuleService}}''' - Tracks available modules, and provides the infrastructure for executing them.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/module | class = ModuleService}}''' - Tracks available modules, and provides the infrastructure for executing them.
* '''{{Javadoc | package = org/scijava/object | class = ObjectService}}''' - Tracks available objects of various types, including {{Javadoc | package = net/imagej | class = Dataset}}s and {{Javadoc | package = org/scijava/display | class = Display}}s.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/object | class = ObjectService}}''' - Tracks available objects of various types, including {{Javadoc | package = net/imagej | class = Dataset}}s and {{Javadoc | package = org/scijava/display | class = Display}}s.
* '''{{Javadoc | package = org/scijava/options | class = OptionsService}}''' - Tools for managing program settings.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/options | class = OptionsService}}''' - Tools for managing program settings.
* '''{{Javadoc | package = org/scijava/platform | class = PlatformService}}''' - Provides hooks for extending the application's behavior depending on the deployment platform (operating system, version of Java, etc.).
+
* '''{{Javadoc | project = SciJava | package = org/scijava/platform | class = PlatformService}}''' - Provides hooks for extending the application's behavior depending on the deployment platform (operating system, version of Java, etc.).
* '''{{Javadoc | package = org/scijava/plugin | class = PluginService}}''' - Tracks available plugins, and provides the infrastructure for executing them (using the {{Javadoc | package = org/scijava/module | class = ModuleService}}).
+
* '''{{Javadoc | project = SciJava | package = org/scijava/plugin | class = PluginService}}''' - Tracks available plugins, and provides the infrastructure for executing them (using the {{Javadoc | package = org/scijava/module | class = ModuleService}}).
* '''{{Javadoc | package = org/scijava/app | class = StatusService}}''' - Publishes status updates for ongoing operations.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/script | class = ScriptService}}''' - Provides utilities for running scripts and macros.
* '''{{Javadoc | package = org/scijava/thread | class = ThreadService}}''' - Manages multithreading.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/app | class = StatusService}}''' - Publishes status updates for ongoing operations.
* '''{{Javadoc | package = org/scijava/tool | class = ToolService}}''' - Tracks available tools—logic binding user input to behavior—as well as the active tool (selected on the toolbar).
+
* '''{{Javadoc | project = SciJava | package = org/scijava/thread | class = ThreadService}}''' - Manages multithreading.
* '''{{Javadoc | package = org/scijava/ui | class = UIService}}''' - Discovers and launches a user interface for interacting with ImageJ.
+
* '''{{Javadoc | project = SciJava | package = org/scijava/tool | class = ToolService}}''' - Tracks available tools—logic binding user input to behavior—as well as the active tool (selected on the toolbar).
 +
* '''{{Javadoc | project = SciJava | package = org/scijava/ui | class = UIService}}''' - Discovers and launches a user interface for interacting with ImageJ.
  
 
=== ImageJ services ===
 
=== ImageJ services ===
Line 54: Line 45:
 
* '''{{Javadoc | package = net/imagej | class = DatasetService}}''' - Tools for creating and managing image data.
 
* '''{{Javadoc | package = net/imagej | class = DatasetService}}''' - Tools for creating and managing image data.
 
* '''{{Javadoc | package = net/imagej/display | class = ImageDisplayService}}''' - Similar to {{Javadoc | package = org/scijava/display | class = DisplayService}}, but specifically for {{Javadoc | package = net/imagej/display | class = ImageDisplay}}s.
 
* '''{{Javadoc | package = net/imagej/display | class = ImageDisplayService}}''' - Similar to {{Javadoc | package = org/scijava/display | class = DisplayService}}, but specifically for {{Javadoc | package = net/imagej/display | class = ImageDisplay}}s.
* '''{{Javadoc | package = net/imagej/overlay | class = OverlayService}}''' - Tools for creating and managing image overlays and regions of interest (ROIs).
+
* '''{{Javadoc | package = net/imagej/display | class = OverlayService}}''' - Tools for creating and managing image overlays and regions of interest (ROIs).
  
 
=== SCIFIO services ===
 
=== SCIFIO services ===
Line 68: Line 59:
 
== Modules ==
 
== Modules ==
  
Each module known to the system (via the {{Javadoc | package = org/scijava/module | class = ModuleService}} can have a <code>menuPath</code> that says where it should live (by default) in the menu. It is also has a <code>menuRoot</code> that says in ''which'' menu it should live, with the default being the <code>APPLICATION_MENU_ROOT</code>, indicating the main application menu structure.
+
Each module known to the system (via the {{Javadoc | package = org/scijava/module | class = ModuleService}} can have a <code>menuPath</code> that says where it should live (by default) in the menu. It also has a <code>menuRoot</code> that says in ''which'' menu it should live, with the default being the <code>APPLICATION_MENU_ROOT</code>, indicating the main application menu structure.
  
 
== MenuService ==
 
== MenuService ==
Line 81: Line 72:
  
 
When modules are added, removed or changed (via {{Javadoc | package = org/scijava/module/event | class = ModulesAddedEvent}}, {{Javadoc | package = org/scijava/module/event | class = ModulesRemovedEvent}}, {{Javadoc | package = org/scijava/module/event | class = ModulesUpdatedEvent}}), the <code>MenuService</code> listens and updates the associated <code>ShadowMenu</code>(s) accordingly. It notifies interested parties that it has done so by firing a corresponding event: {{Javadoc | package = org/scijava/menu/event | class = MenusAddedEvent}}, {{Javadoc | package = org/scijava/menu/event | class = MenusRemovedEvent}}, or {{Javadoc | package = org/scijava/menu/event | class = MenusUpdatedEvent}}.
 
When modules are added, removed or changed (via {{Javadoc | package = org/scijava/module/event | class = ModulesAddedEvent}}, {{Javadoc | package = org/scijava/module/event | class = ModulesRemovedEvent}}, {{Javadoc | package = org/scijava/module/event | class = ModulesUpdatedEvent}}), the <code>MenuService</code> listens and updates the associated <code>ShadowMenu</code>(s) accordingly. It notifies interested parties that it has done so by firing a corresponding event: {{Javadoc | package = org/scijava/menu/event | class = MenusAddedEvent}}, {{Javadoc | package = org/scijava/menu/event | class = MenusRemovedEvent}}, or {{Javadoc | package = org/scijava/menu/event | class = MenusUpdatedEvent}}.
 +
 +
= API Version History =
 +
 +
A history of API changes is available at:
 +
https://abi-laboratory.pro/java/tracker/timeline/scijava-common/
  
 
= Further reading =
 
= Further reading =
  
* [http://www.scijava.org/ SciJava web site]
+
* [http://scijava.org/ SciJava web site]
* [http://www.scijava.org/scijava-common/scijava-common.html SciJava Common presentation]
+
* [http://scijava.org/scijava-common/scijava-common.html SciJava Common presentation]
* {{GitHub|org=imagej|repo=imagej-tutorials|label=ImageJ tutorials}}
+
* {{GitHub|org=imagej|repo=tutorials|label=ImageJ tutorials}}
 
* {{GitHub|org=scijava|repo=scijava-common|label=SciJava Common source code}}
 
* {{GitHub|org=scijava|repo=scijava-common|label=SciJava Common source code}}

Latest revision as of 09:08, 3 December 2018

SciJava Common
Project SciJava
URL https://github.com/scijava/scijava-common
Source on GitHub
License BSD-2
Release 2.64.0
Date Wed May 24 12:57:32 CDT 2017
Development status Active
Support status Active
Team
Founders Curtis Rueden, Mark Hiner
Leads Curtis Rueden
Developers Curtis Rueden
Debuggers Curtis Rueden
Reviewers Curtis Rueden
Support Curtis Rueden
Maintainers Curtis Rueden
Contributors Mark Hiner, Johannes Schindelin, Chris Allan, Barry DeZonia, Christian Dietz, Richard Domander, Gabriel Einsdorf, Aivar Grislis, Jonathan Hale, Grant Harris, Lee Kamentsky, Rick Lentz, Melissa Linkert, Kevin Mader, Hadrien Mary, Alison Walter, Jay Warrick

SciJava Common is a common library for SciJava software. It provides a plugin framework, with an extensible mechanism for service discovery, backed by its own annotation processor, so that plugins can be loaded dynamically. It is used by both ImageJ and SCIFIO.

Plugin framework

First and foremost, SciJava Common is a plugin framework—a base for developing highly modular and extensible Java applications.

Plugin discovery

All plugins available on Java's classpath are automatically discovered and made available. This is accomplished by scanning classpath resources for the file path META-INF/json/org.scijava.plugin.Plugin. Such files are generated at compile time by a Java annotation processor that writes them in response to @Plugin annotations on Java classes, an idea inspired by the SezPoz project.

Application container

All program state, such as available plugins, is accessible from a root object known as the application context.

Services

Imagej1-icon.png
Whereas ImageJ1 is a singleton, with static methods to access much of its functionality, ImageJ2 encapsulates its program state in the application context, allowing multiple simultaneous such contexts in the same JVM.

ImageJ encapsulates its various parts as separate "services" that provide related state functionality and track related program state. An instance of the ImageJ class is nothing more than a collection of these services; this instance is referred to as the "application gateway." Services are defined as interfaces, with concrete implementations as plugins. This design provides seams in the right places so that behavior at every level can be customized and overridden.

SciJava services

Here are a few of SciJava Common's major core services:

  • AppService - Tracks software applications (SCIFIO, ImageJ, etc.) present in the context.
  • DisplayService - Tracks available displays, as well as the active display, and provides the means to create new displays to visualize data.
  • EventService - Publishes events to the event bus, and allows interested parties to subscribe to them. The service provides the central means of communication between various parts of the codebase.
  • IOService - General tools for opening and saving data within the context.
  • MenuService - Builds the application menu structure.
  • ModuleService - Tracks available modules, and provides the infrastructure for executing them.
  • ObjectService - Tracks available objects of various types, including Datasets and Displays.
  • OptionsService - Tools for managing program settings.
  • PlatformService - Provides hooks for extending the application's behavior depending on the deployment platform (operating system, version of Java, etc.).
  • PluginService - Tracks available plugins, and provides the infrastructure for executing them (using the ModuleService).
  • ScriptService - Provides utilities for running scripts and macros.
  • StatusService - Publishes status updates for ongoing operations.
  • ThreadService - Manages multithreading.
  • ToolService - Tracks available tools—logic binding user input to behavior—as well as the active tool (selected on the toolbar).
  • UIService - Discovers and launches a user interface for interacting with ImageJ.

ImageJ services

Some of the services which ImageJ adds:

SCIFIO services

SCIFIO provides several additional services—in particular:

Menuing system

The SciJava menuing system is divided into several layers, to make it easier to override its behavior or customize its appearance in a user interface.

Modules

Each module known to the system (via the ModuleService can have a menuPath that says where it should live (by default) in the menu. It also has a menuRoot that says in which menu it should live, with the default being the APPLICATION_MENU_ROOT, indicating the main application menu structure.

MenuService

The MenuService takes care of constructing ShadowMenu tree structures for all available modules in the system, using their menuPath and menuRoot values. These tree structures are UI-agnostic. There is one ShadowMenu per menuRoot, which can be requested at will from the MenuService.

User interfaces

The UIService then takes care of constructing an actual UI-specific menu bar (or whatever UI components and/or widgets it wants) from the available ShadowMenus. There is a type hierarchy beneath the MenuCreator interface intended for this purpose; for example, the SwingJMenuBarCreator implements MenuCreator to create and maintain a Swing JMenuBar that reflects the state of a particular ShadowMenu.

How changes propagate

When modules are added, removed or changed (via ModulesAddedEvent, ModulesRemovedEvent, ModulesUpdatedEvent), the MenuService listens and updates the associated ShadowMenu(s) accordingly. It notifies interested parties that it has done so by firing a corresponding event: MenusAddedEvent, MenusRemovedEvent, or MenusUpdatedEvent.

API Version History

A history of API changes is available at: https://abi-laboratory.pro/java/tracker/timeline/scijava-common/

Further reading