BEAM 4 Modules

BEAM 4 introduces a module-based architecture. The monolithic beam.jar as of BEAM 3.x has been split into several, self-standing modules, each having a unique identifier and a version number. BEAM modules can be installed, updated and uninstalled via the VISAT module manager. All modules are located in the modules directory of the BEAM installation.

Module Format

Basically, a BEAM module is a common Java archive file (JAR) or a directory containing Java class files. What makes this JAR (or directory) a BEAM module is the presence of a module manifest file, called module.xml. The module manifest is located at the top level of the module. Here is the minimum structure of a module called baztool:

   +- <baztool.jar>
      |
      |- com/acme/beam/baztool/*.class
      |
      `- module.xml      

Where com/acme/beam/baztool is an arbitrary package path suitable for your module's implementation classes.

The VISAT module manager will additionally look for the presence of an optional about.html in the top level of a module and display it to the user. It is a good practice to add this file to your module. It may contain any valid HTML:

   +- <baztool.jar>
      |
      |- com/acme/beam/baztool/*.class
      |
      |- about.html (optional)
      `- module.xml      

More information on modules can be found in Configuration Management and Ceres.

Module Descriptor Format

The format of the BEAM module descriptor file is self-explaining. This is a simple module descriptor:

<module>
    <!-- The version of the manifest format -->
    <manifestVersion>1.0.0</manifestVersion> 

    <!-- The unique, symbolic name of the module -->
    <symbolicName>beam-baztool</symbolicName>

    <!-- The version of the module -->
    <version>1.2</version> 

    <!-- Dependencies on other installed modules -->
    <!-- The BEAM Core module will always be required. -->
    <dependency>
        <module>beam-core</module>
    </dependency>
    <!-- The following dependency on VISAT is optional, -->
    <!-- e.g. because VISAT may not be required if module can be run in batch mode. -->
    <dependency>
        <module>beam-visat</module>
        <optional>true</optional>
    </dependency>
</module>

Its a good practice to also provide the following elements:

<module>
    <!-- ... -->

    <!-- A human-readable name for the module -->
    <name>Baz Compensator Tool</name>
    <!-- A human-readable description -->
    <description>Compensates fuzzles found in a baz and replaces them by snots.</description>

    <vendor>ACME Ltd.</vendor>
    <contactAddress>gruntz@acme.zq</contactAddress>
    <copyright>(C) 2007 by ACME Ltd.</copyright>
    <url>http://www.acme.zq/beam-tools/</url>
    <licenseUrl>http://www.gnu.org/licenses/gpl.html</licenseUrl>

    <!-- You can review commonly used categories in the VISAT module manager -->
    <categories>VISAT,Processor,Baz</categories>

    <!-- Tell the user what has changed since the last release -->
    <changelog>
        <![CDATA[
          <p>Changes in 1.2 <br/>
             Added a gruntz to the baz extender. <br/>
             The baz can now also sing. <br/>
          </p>
        ]]>
    </changelog>

    <!-- ... -->
</module>

Module Activation

If the module needs perform some Java code when it is activated, just before the application (ee.g. VISAT)
starts up or before it shuts down you can provide an activator. The activator must implement the
com.bc.ceres.core.runtime.Activator interface provided by the Ceres module and must reside with the module.

<module>
    <!-- ... -->

    <!-- Provides code executed before the app starts and while being stopped. -->
    <activator>com.acme.beam.baztool.BazToolActivator</activator>

    <!-- ... -->
</module>

A module activator is instantiated only once during the lifetime of the application. You can consider it to be a singleton.

Extending BEAM

As of BEAM 4, two basic types of extension mechanisms are supported:

1. Extensions declared in the META-INF/services directory of the module JAR or directory
2. Extensions declared in the module's manifest module.xml

todo: describe when to use which type

1. Extensions declared in the META-INF/services Directory

The first type uses the standard Java service provider interface (SPI) configuration files. An SPI configuration file is a plain text file located in the directory META-INF/services of your module JAR. The name of the configuration file is the fully qualified class name of an SPI class provided by the BEAM API. You simply have to place the fully qualified class name of your implementation of the SPI in the configuration file. The BEAM API provides the following SPI extension points:

For detailed information on the BEAM SPI API, please consult the BEAM API documentation.
Various realisations implementations of SPIs can be found in the source code of many standard BEAM modules: beam-core, beam-visat, beam-help, beam-mosaic, beam-landsat-reader, etc. See also Build from Source.
For detailed information on Java SPI configuration files, please refer to JAR File Specification.

2. Extension Points declared in the Module Manifest

Module manifest extension points are only recognized if VISAT is started, because this is currently (BEAM 4.1) the only application in BEAM which uses the Ceres module runtime. The command line tools construct their classpath dynamically by adding all JARs found in the lib and modules directories of the BEAM installation. In this case, only the SPI extension mechanism as described above can be used.

Various realisations (extensions and implementations) of these extension points can be found in the module.xml of many standard BEAM modules: beam-core, beam-visat, beam-help, beam-mosaic, beam-landsat-reader, etc. See also Build from Source.
For more information on the ToolViewDescriptor and Command classes please consult the BEAM API documentation and implementations in the BEAM source code.