Skip to end of metadata
Go to start of metadata

Motivation

Ceres (Wikipedia) is a platform for pluggable Java modules. It provides to BEAM the capability to install and update modules from a central module repository.

Platform Overview

  1. The platform provides one or more module <i>runtimes</i>. A runtime is invoked using the ceres-launcher.jar.
  2. Each runtime manages one or more modules.
  3. A module is a JAR or a directory which has a file module.xml in its root. This file is the module manifest, which provides module metadata, such as name, version, description, dependencies, etc.
  4. There is one system module instance per runtime. The system module's name is ceres-core.
  5. All modules implicitly depend on the system module.
  6. A module can have explicit dependencies on other modules.
  7. Each module has its own classpath (thus class loader) which is defined by all other modules on which the module depends.
  8. If a module is a directory (and not a JAR), all JARs found in that directory are automatically added to the module's classpath.
  9. Each module can expose one or more extension points.
  10. Each module can expose one or more extensions which extend a certain extension point.
  11. A module can have an activator, which is coded in Java and is invoked when the runtime starts and stops.

Typical Application Directory Structure

The typical standard directory for an application based on Ceres is:

  +- <app-home>/
     | 
     +- bin/
     |  |
     |  |- ceres-launcher.jar
     |  |- <app>.sh    (Unix)
     |  |- <app>.bat   (Windows)
     |  `- ...
     | 
     +- config/
     |  |
     |  `- <app>.config
     | 
     +- <lib>/
     |  |
     |  `- *.jar
     | 
     +- <modules>/
        |
        `- *.jar

Explanations:

<app-home>/

Home directory of application <app>

bin/

Location where the application lauchers are installed. Should also contain ceres-launcher.jar which provides the main entry point.

config/

Optional location where configuration files are installed. If file <app>.config exists here, it is read by the launcher in order to configure the application. If this file does not exist, the directory structure as shown above is assumed by default.

<lib>/

Location with common libraries. If it exists, the launcher automatically adds all Java libraries (JARs and directories) to the classpath of each module. The actual name of this directory is configurable by adapting <app>.config. The default name is lib.

<modules>/

Mandatory location where installed modules are kept. The actual name of this directory is configurable by adapting <app>.config. The default name is modules.

Note that Ceres does not limit <app-home>/ to contain only a single application. You can configure as much applications as you like. Each application can be configured separately. Simply place a <app>.config in the config/ directory.

Launching an Application

A Ceres-based application is started using the launcher ceres-launcher.jar.

For example, from a Windows batch file (*.bat):

set BEAM4_HOME=C:\Programme\beam-4.11
java.exe ^
    -Xmx1024M ^
    -Dceres.context=beam ^
    -Dbeam.app=VisatMain ^
    "-Dbeam.home=%BEAM4_HOME%" ^
    -jar "%BEAM4_HOME%\bin\ceres-launcher.jar" %*

or a Unix script (*.sh):

export BEAM4_HOME=C:\Programme\beam-4.11
java \
    -Xmx1024M \
    -Dceres.context=beam \
    -Dbeam.app=VisatMain \
    "-Dbeam.home=$BEAM_HOME" \
    -jar "$BEAM4_HOME\bin\ceres-launcher.jar" "$@"

The Java property ceres.context sets the application context name for a runtime, beam in the example above. Once the application context name is known, the Ceres launcher honours a number of configuration parameters of the form -D<context>.<property>=<value>. In the example above beam.app tells Ceres which application to launch. The value of this parameter must be the name of a registered Ceres application. In the example above, the value is VisatApp. This name is defined in the module.xml of the BEAM module beam-visat:

<extension point="ceres-core:applications">
    <application id="VisatMain" class="org.esa.beam.visat.VisatMain"/>
</extension>

The implementing class is org.esa.beam.visat.VisatMain, it implements the Ceres core interface com.bc.ceres.core.runtime.RuntimeRunnable, which is used by Ceres to launch applications.

Configuring the Launcher

The Ceres configuration parameters can be passed as Java system properties on the Java command line (see example above) or also in the <app>.config file which has Java Properties format. The mandatory Ceres configuration parameters are:

Property

Description

<context>.home

The application's home directory. Used by the launcher to find more configuration information and default locations.

<context>.app

The application identifier. Must be the name of an extension of the ceres-core:applications extension point.

Other configuration parameters are best understood by reading the configuration file for BEAM:
beam.config