Build Plug-ins

How to build and install a plug-in

This page describes how to build new Weasis plug-ins and how they can be incorporated into the distributions, see also this page for the IDE configuration.

List of plug-ins types

  • Media viewer or editor (main central panel that implements ViewerPlugin or ImageViewerPlugin and the factory implements SeriesViewerFactory)
  • Toolbar associated with a viewer (implements Toolbar)
  • Tool associated with a viewer (right panel that implements DockableTool)
  • Data Explorer (data model implements DataExplorerModel and data view implements DataExplorerView, and the factory implements DataExplorerViewFactory)
  • Import data into an explorer (ex. ImportDicom and the factory implements DicomImportFactory)
  • Export data into an explorer (ex. ExportDicom and the factory implements DicomExportFactory)
  • DICOM editor or viewer for special modalities (DicomSpecialElementFactory and SeriesViewerFactory), see weasis-dicom-sr
  • Media codec (implements Codec)
  • Preferences (implements PreferencesPageFactory)
  • UI aggregator. This is the application main user interface bundle. The maven artifact of this bundle must be defined in config.properties (ex. weasis.main.ui=weasis-base-ui)
Tip

See the Weasis Architecture to understand the plug-in hierarchy.

Build plug-ins from Maven archetype

  1. From the folder Weasis/archetype execute: mvn install
  2. Generate a sample project by executing the following command: mvn archetype:generate -DarchetypeCatalog=local
  3. Select the archetype:
    • weasis-plugin-base-viewer-archetype (example of a toolbar and a tool for the non DICOM viewer)
    • weasis-plugin-dicom-viewer-archetype (example of a toolbar and a tool for the DICOM viewer)
Note

From Eclipse: File > New > Maven Project and Search for weasis archetype in catalog filter.
From Intellij: File > New Project > Maven, select the “Maven Archetype” generators and select a Weasis archetype from Default local catalog.

Tip

In the pom.xml of the new plug-in, the tag <relativePath> must be adapted to your relative path of Weasis sources.
The default value is <relativePath>../Weasis/weasis-parent/pom.xml</relativePath>

Install plug-ins

Warning

This documentation has not been updated since version 4.2.0 where the properties configuration files have been replaced by json files.

The way to add plugins will also evolve soon with the new weasis-manager component.

For the installed distribution

The file “app/conf/ext-config.properties” must be adapted and plug-ins must be placed in the directory “app/plugins”.

Example with weasis-isowriter:

  • Add in app/conf/ext-config.properties:

    felix.auto.start.85=${weasis.codebase.url}/plugins/weasis-isowriter-2.6.1.jar
    Tip

    If you want to use another directory for a plugin on your computer, you should use one of the following properties:
    On Windows: felix.auto.start.85=file:///C:/path/to/weasis-isowriter-2.6.1.jar
    On linux: felix.auto.start.85=file:///home/Username/path/to/weasis-isowriter-2.6.1.jar
    On macOS: felix.auto.start.85=file:///Users/Username/path/to/weasis-isowriter-2.6.1.jar

    Tip

    For not modifying the current ext-config.properties create a new file and add to the launcher the following VM argument: -Dfelix.extended.config.properties="file:///your_plugin_path/myplugin-config.properties"

  • Place the file “weasis-isowriter-2.6.1.jar” in the directory “/weasis/plugins”

For the WEB distribution

Build a new war file containing the plug-ins and the ext-config.properties file.

  • Build “weasis-ext.war” with the following structure:

        weasis-ext/
        ├── conf/
        │   ├── ext-config.properties
        ├── WEB-INF/
        │   ├── web.xml
        ├── plugin1.jar
        └── plugin2.jar

  • In /weasis-ext/conf/ext-config.properties, add the plug-ins references:

    felix.auto.start.85= \
     ${weasis.codebase.ext.url}/plugin1.jar \
     ${weasis.codebase.ext.url}/plugin2.jar
    Note

    Using ${weasis.codebase.ext.url} allows you to keep the base URL abstract, so moving the package to another server won’t be a problem. Otherwise absolute URLs must be used. The default value of ${weasis.codebase.ext.url} is ${weasis.codebase.url}-ext.

  • weasis-ext is the default web context when launching Weasis, using another web context requires modifying the property weasis.ext.url, it can be done by:

    weasis.ext.url=${server.base.url}/weasis-newext

  • Changing the property in weasis-pacs-connector configuration.

    Note

    It is also possible to add the code base for plugins (cdb-ext) directly in the URL:

    http://localhost:8080/weasis-pacs-connector/viewer?patientID=9702672&cdb-ext=http://localhost:8080/plugins/weasis-ext

Tip

For debugging a specific configuration: add to the launcher the following VM argument: -Dfelix.extended.config.properties="http://server:port/weasis-ext/conf/ext-config.properties

An example that makes a package of weasis-isowriter plugin:

  • Build “weasis-ext.war”:
        weasis-ext/
        ├── conf/
        │   ├── ext-config.properties
        ├── WEB-INF/
        │   ├── web.xml
        └── weasis-isowriter-2.0.3.jar

Build OSGi services

All the plug-in type described in the list above are OSGi services that are registered and aggregated in the GUI. Building the plug-in from the Maven archetype will configure the OSGi service automatically. For adding new OSGi services, here is the procedure:

  1. Create a class implementing one of the plug-in types and add at least the annotations @Component and @Service, for instance:

    @Component(immediate = false)
    @Service
    public class SamplePrefFactory implements PreferencesPageFactory {
      ...
    }
    Tip

    For more information about annotations see the Apache Felix SCR Annotations.

  2. Add in pom.xml of the plug-in the maven-scr-plugin (to generate XML file from the Java annotations) and the property for loading any XML file in maven-bundle-plugin:

        <build>
        <plugins>
         <plugin>
            <groupId>org.apache.felix</groupId>
            <artifactId>maven-scr-plugin</artifactId>
         </plugin>
         <plugin>
            <groupId>org.apache.felix</groupId>
            <artifactId>maven-bundle-plugin</artifactId>
         </plugin>
        ...