Migrate 3.x Processor to 4.x

Skip to end of metadata
Go to start of metadata

Migrating a Processor for BEAM 3.x to BEAM 4.x

This guide will lead you through the steps needed to be done to convert a processor for BEAM 3.x into a processor for BEAM 4.x. Make sure you first had a look at Source Code Migration Guide and also Using the BEAM API.

First of all we will set up an appropriate project. Therefore you can choose between two ways you can go. The first is very simple to setup and is good when you want to develop for a released version or for a first try of developing for BEAM , but if you want stay up to date with the latest development of of BEAM you should choose the second one.

  1. Create a new Java project in your preferred IDE.
      1. Next you have to add the modules to your project to which it will depend. In most cases you will need the modules beam-core, beam-visat, beam-ui, beam-envisat-reader and beam-processing. You can find those modules in the modules folder of your BEAM installation directory.
      2. Optionally you can redirect the created compile output into the modules folder of your BEAM installation directory. If you do so you can start your installed BEAM and your processor will be loaded automatically and you can use it in VISAT.
      3. Now you can go on with the next step. If you've chosen this approach you don't have to care about all the maven stuff in the following steps. You can ignore all notes about pom.xml file and the maven directory structure.
    2. For the second approach you should first follow the steps given on the following page Build from Source.
      1. On the command-line, change to the BEAM 4.x project directory which you have created in the first step. All file references in this guide are relative to this directory from here on.
      2. Use the Maven archetype command to create a maven project file (pom.xml) and an initial directory structure for your BEAM processor 
        > mvn archetype:create -DgroupId=my.processor -DartifactId=beam-my-processor -Dversion=1.1 -Dpackaging=jar

        By convention, the groupId parameter shall reflect your main package path where the Java class files resist. In this example this is my.processor.The artifactId parameter will be used as name for the resulting module directory within the BEAM project directory and also for the resulting module JAR file (beam-my-processor-1.1.jar in the example). The Maven archetype command should now have created a new module in the BEAM project directory with this layout:

        beam-my-processor
 |-- src
 |   |-- main
 |   |   `-- java
 |   |       `-- my
 |   |           `-- processor
 |   |               `-- App.java
 |   `-- test
 |       `-- java
 |           `-- my
 |               `-- processor
 |                   `-- AppTest.java
  `-- pom.xml
      3. You should now run the maven package command from the command line to verify that your module is successfully integrated into the BEAM project file. Move to the BEAM 4.x project directory an type 
        > mvn package

        As a result you should now find beam-my-processor/target/beam-my-processor-1.1.jar.

      4. Run an appropriate Maven IDE command to update the BEAM project files for your IDE. E.g. use either 
        > mvn idea:idea
        > mvn eclipse:eclipse
      5. After reloading the BEAM project in your IDE you should now see a new module named beam-my-processor
        within the BEAM project structure.
  2. We will now integrate the existing source code into the new module.
    The dummy files App.java and AppTest.java created by the archetype command can now safely be deleted.
    Conforming to the Maven Standard Directory Layout,
    copy your source files into beam-my-processor/src/main/java/my/processor and if you have JUnit tests also into beam-my-processor/src/test/java/my/processor. If your module comprises resources (sources other than Java files) create a
    directory beam-my-processor/src/main/resources. In our example we have to copy the auxdata
    directory into the resources directory so that we get beam-my-processor/src/main/resources/auxdata.
    If the auxdata shall be accessible to user you have to install those data.
    There for you should override initProcessor in your Processor implementation and call installAuxdata().
    All data in beam-my-processor/src/main/resources/auxdata will be copied to USER_HOME/.beam/beam-my-processor/auxdata by default.
  3. We will now have to update the Maven project file beam-my-processor/pom.xml with all required BEAM library dependencies.
    The dependencies section of the POM should look like this: 
    <dependencies>
  <dependency>
    <groupId>org.esa.beam</groupId>
    <artifactId>beam-core</artifactId>
    <version>4.X-SNAPSHOT</version>
  </dependency>
  <dependency>
    <groupId>org.esa.beam</groupId>
    <artifactId>beam-visat</artifactId>
    <version>4.X-SNAPSHOT</version>
  </dependency>
</dependencies>

    You have to replace 4.X-SNAPSHOT by the current version of the dependency module.

  4. Now we can go on to adopt the source code to the changes made to API.
    The changes you have to honor are listed tn the following table
    Class Changes
    org.esa.beam.framework.processor.RequestElementFactory createInputProductRef(URL url, String fileFormat, String typeId)
    createInputProductRef(File file, String fileFormat, String typeId)
      createOutputProductRef(URL url, String fileFormat, String typeId)
    createOutputProductRef(File file, String fileFormat, String typeId)
    org.esa.beam.framework.processor.Processor process()
    process(com.bc.ceres.core.ProgressMonitor pm)
    com.bc.progress.* No longer exists.
    org.esa.beam.util.ProcessorUtils moved to org.esa.beam.framework.processor.ProcessorUtils
    org.esa.beam.framework.processor.ProductRef ProductRef(URL url, String fileFormat, String typeId)
    ProductRef(File file, String fileFormat, String typeId)
    org.esa.beam.visat.AbstractProcessorPlugIn No longer exists. Move the information provided by your implementation into a VISAT extension beam-visat:actions in your module.xml
  5. Before we go on you should read the following guide about extending BEAM.
  6. Now we'll move the so far provided information by your AbstractProcessorPlugIn implementation to the module.xml.
    This will result in an extension element within the module manifest. Which might look similar to the following example. 
    <extension point="beam-visat:actions">
  <action>
    <id>MyProcessorPlugIn</id>
    <class>org.esa.beam.visat.actions.ProcessorAction</class>
    <processor>my.Processor.MyProcessor</processor>
    <text>My personal Processor ...</text>
    <shortDescr>Invoke my personal processor.</shortDescr>
    <mnemonic>P</mnemonic>
    <parent>tools</parent>
    <helpID>MyProcessorPlugIn</helpID>
    <placeAfter>Binning</placeAfter>
  </action>
</extension>
  7. If you have any dependency to other modules like the Envisat reader or the SMAC processor you have to include these dependencies
    into the module manifest and also into the Maven POM file.
    Maven POM Dependency Example
    <dependency>
  <groupId>org.esa.beam</groupId>
  <artifactId>beam-meris-smac</artifactId>
  <version>1.5</version>
</dependency>

<dependency>
  <groupId>org.esa.beam</groupId>
  <artifactId>beam-envisat-reader</artifactId>
  <version>1.1-SNAPSHOT</version>
</dependency>
    Module Manifest Dependency Example
    <dependency>
  <module>beam-envisat-reader</module>
  <version>1.1-SNAPSHOT</version>
</dependency>

<dependency>
  <module>beam-meris-smac</module>
  <version>1.5</version>
</dependency>
  8. As the last step we replace the old ProgressControler by the new ProgressMonitor. You get an instance of this class as parameter into your process(ProgressMonitor pm) method. All methods of the old ProgressControler class do have an equivalent representation in the new ProgressMonitor class. You should replace them as follows:
    • pc.fireProcessStarted("task", min, max) --> pm.beginTask("task", totalWork)
    • pc.fireProcessInProgress(value) --> pm.worked(ammount)
    • pc.fireProcessEnded() --> pm.done()
    • pc.isTerminationRequested() --> pm.isCanceled()

Results

The following shows you how the POM and the module manifest might look like.

The Maven POM File
<project
        xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.esa.beam</groupId>
        <artifactId>beam</artifactId>
        <version>4.X</version>
    </parent>

    <name>My Personal Processor</name>
    <groupId>my.processor</groupId>
    <artifactId>beam-my-processor</artifactId>
    <version>1.1</version>

    <packaging>jar</packaging>

    <dependencies>
        <dependency>
            <groupId>org.esa.beam</groupId>
            <artifactId>beam-visat</artifactId>
        </dependency>
        <dependency>
            <groupId>org.esa.beam</groupId>
            <artifactId>beam-processing</artifactId>
        </dependency>
        <dependency>
            <groupId>org.esa.beam</groupId>
            <artifactId>beam-envisat-reader</artifactId>
        </dependency>

    </dependencies>
</project>
The Module Manifest File
<module>
    <manifestVersion>1.0.0</manifestVersion>
    <symbolicName>beam-my-processor</symbolicName>
    <version>1.1</version>
    <name>My Personal Processor</name>

    <description>
        This is a short description of my personal processor.
    </description>

    <dependency>
        <module>beam-processing</module>
    </dependency>
    <dependency>
      <module>beam-envisat-reader</module>
      <version>1.1-SNAPSHOT</version>
    </dependency>
    <dependency>
        <module>beam-visat</module>
        <optional>true</optional>
    </dependency>

    <categories>Application,Processor</categories>

    <extension point="beam-visat:actions">
        <action>
            <id>MyProcessorPlugIn</id>
            <class>org.esa.beam.visat.actions.ProcessorAction</class>
            <processor>my.Processor.MyProcessor</processor>
            <text>My personal Processor ...</text>
            <shortDescr>Invoke my personal processor.</shortDescr>
            <mnemonic>P</mnemonic>
            <parent>tools</parent>
            <helpID>MyProcessorPlugIn</helpID>
            <placeAfter>Binning</placeAfter>
        </action>
    </extension>

</module>
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.