Getting started - GeoscienceAustralia/earthsci GitHub Wiki

This page provides a brief overview of the project, its structure, and how to obtain and build the source code.

Contents

Overview

The EarthSci RCP project is a Java based platform built on Eclipse e4 / RCP. It's primary purpose is for the visualisation of earth science data, and it makes extensive use of the NASA World Wind Java SDK to provide a 3D virtual globe visualisation environment.

The project started life as a platform migration for the existing GA World Wind Suite with an aim to:

  • Address identified usability issues
  • Make the codebase easier to extend and maintain
  • Introduce a modular plugin based architecture to make it easier to add additional functionality

The e4/RCP platform was chosen because it provides a number of desired features out-of-the-box, including:

  • Comprehensive and mature UI toolkit with support for dockable views and wizards etc.
  • Powerful plugin architecture that allows for developing, managing and updating plugins from remote sources
  • Powerful internationalization features
  • Powerful CSS-based styling features
  • In-built help and 'tips' mechanisms

For developers unfamiliar with Eclipse development, take a look at the excellent tutorials maintained by Lars Vogel at Vogella.com.

Project structure

The overall project structure is as follows:

-- pom.xml				The master POM file. Will build all plugins, features and products.
|- parent-pom.xml		A common parent POM that should be referenced by all plugin POMs.
|- externals\			Contains all included third-party plugins (e.g. NASA World Wind)
|- plugins\				Contains all plugin projects developed as part of the platform. This includes test plugins.
|- features\			Contains all feature projects developed as part of the platform. This includes product features.
|- webstart\			Contains a utility project used to generate webstart JNLP definitions for
|- verifier\			Contains a utility project that checks the configuration of plugins and features and fails the build if it detects mis-configured projects etc.

Plugins and Features

The project follows the Eclipse application pattern, and is composed of a number of plugins (or bundles) and features (groups of plugins that are related).

Plugin Description
au.gov.ga.earthsci.core The core, non-UI components of the EarthSci platform
au.gov.ga.earthsci.core.tests Tests for the core plugin
au.gov.ga.earthsci.application The core UI components of the EarthSci platform
au.gov.ga.earthsci.application.tests Tests for the application UI plugin
au.gov.ga.earthsci.common Shared, reusable non-UI components
au.gov.ga.earthsci.common.tests Tests for the common components
au.gov.ga.earthsci.common.ui Shared, reusable UI components
au.gov.ga.earthsci.eclipse.extras A copy of some internal Eclipse RCP components for use in the application
au.gov.ga.earthsci.jface.extras A copy of some internal JFace components for use in the application
org.eclipse.ui.workbench.compatibility Some adapters for working with the Workbench in an e4 application
au.gov.ga.earthsci.injectable Provides a mechanism for having arbitrary objects participate in the DI mechanism
au.gov.ga.earthsci.intent The Intent API
au.gov.ga.earthsci.logging Provides configuration to enable SLF4J logging
au.gov.ga.earthsci.catalog The core Catalog API
au.gov.ga.earthsci.catalog.tests Tests for the core Catalog API
au.gov.ga.earthsci.catalog.ui The basic UI components for the Catalog API
au.gov.ga.earthsci.catalog.ui.tests Tests for the Catalog API UI components
au.gov.ga.earthsci.catalog.dataset A catalog implementation that reads legacy dataset.xml files
au.gov.ga.earthsci.catalog.directory A catalog implementation that reads from a local file system
au.gov.ga.earthsci.catalog.wms A catalog implementation that reads from OGC WMS services
au.gov.ga.earthsci.layer.ui Basic UI components for interacting with the Layer API
au.gov.ga.earthsci.layer.ui.tests Tests for the Layer UI components
au.gov.ga.earthsci.bookmark The core Bookmark API
au.gov.ga.earthsci.bookmark.tests Tests for the core Bookmark API
au.gov.ga.earthsci.bookmark.ui The basic UI components for the Bookmark API
au.gov.ga.earthsci.bookmark.ui.tests Tests for Bookmark API UI components
au.gov.ga.earthsci.notification The core Notification API
au.gov.ga.earthsci.notification.tests Tests for the core Notification API
au.gov.ga.earthsci.notification.ui The basic UI components for the Notification mechanism
au.gov.ga.earthsci.notification.popup A plugin that provides a popup notification receiver
au.gov.ga.earthsci.model The core 3D Model API
au.gov.ga.earthsci.model.tests Tests for the core 3D Model API
au.gov.ga.earthsci.model.core Basic implementations for the 3D Model API
au.gov.ga.earthsci.model.core.tests Tests for the basic 3D Model API implementations
au.gov.ga.earthsci.model.ui Basic UI components for the 3D Model API
au.gov.ga.earthsci.worldwind Extensions and utilities for the NASA WorldWind SDK, used to provided additional layer types etc.
au.gov.ga.earthsci.worldwind.tests Tests for the au.gov.ga.earthsci.worldwind plugin
Feature Description
au.gov.ga.earthsci.feature The core feature of the EarthSci platform
au.gov.ga.earthsci.product The product feature of the EarthSci platform
org.eclipse.rcp.minimal A cut-down Eclipse RCP feature that removes unneeded plugins

Development Environment

The following is the recommended development environment for the project.

Required:

Repositories

Repository URL
E4 http://download.eclipse.org/e4/downloads/drops/S-0.17-201501051100/repository
Sapphire http://download.eclipse.org/sapphire/8/repository

Recommended:

  • Additional Eclipse IDE plugins
    • m2e (Maven integration for Eclipse)
  • Internet access

Get the source code

There are a number of options for obtaining the source code for EarthSci RCP. Each has it's own pros and cons, and the best method for developers depends on their intentions and experience using Git.

The options are described below.

Option 1: Download the project source archive

This option is probably the simplest and is suitable for developers interested in playing with / using the source code with no intention of submitting patches etc.

To download the source code:

  1. Navigate to https://github.com/GeoscienceAustralia/earthsci
  2. Click "Downloads"
  3. Select the format you would like to download the source code in (zip, tarball etc.)
  4. Extract the downloaded source code to a location of your choice

Option 2: Clone a local copy of the Git repository

This option is best for developers familiar with Git but who do not want to fork through github. Cloning the repository will give you access to the full history of the source code and makes it possible to submit patches at a later date.

To clone the repository locally:

  1. Ensure you have Git setup appropriately (see this page if you need help setting up Git)
  2. From a command line, cd to the directory you wish to clone the repository to
  3. Run the following command: >> git clone https://github.com/GeoscienceAustralia/earthsci.git

You should now have a fully functioning local clone of the EarthSci RCP project.

Note: This method will create a read-only repository. You will be unable to push changes back into the remote repository on Github. However, you can create manual patches using git format-patch or similar that can be submitted (although pull requests via Github forks are preferred - see below).

Option 3: Fork the Git repository on github

This is the preferred option for developers who wish to contribute to the ongoing development of the GA EarchSci RCP project. This method is fully supported by Github, making it relatively simple.

To fork the repository follow the instructions here. The URL of the project repository is https://github.com/GeoscienceAustralia/earthsci

Setting up in Eclipse

The source code for earthsci is organised into a collection of Eclipse projects that can be easily imported. Eclipse can be downloaded here. Once you have obtained a copy of the source code, the following approaches can be used to setup the project within Eclipse.

Using Eclipse

This option is appropriate if you downloaded the source code as a zip archive or similar, or if you prefer to interact with Git through a command line or external client etc.

  1. Within Eclipse, goto File -> Import...
  2. Expand "General" folder
  3. Select "Existing projects into Workspace"
  4. Click "Next"
  5. Choose the earthsci directory as the root folder
  6. Select all of the projects
  7. Click "Finish"
  8. Repeat the above for each of the folders plugins/, externals/, features/.

This should import all of the projects into Eclipse and make them available via the package explorer etc.

Additional steps (Optional)

Once the projects have been imported into Eclipse there are some optional steps you can perform.

  1. Setup working sets

    Eclipse uses the notion of 'working sets' to group related projects. We recommend the following working sets:

    • ga-earthsci - Contains the top-level project. Useful for editing the master POM and triggering product builds.
    • ga-earthsci-plugins - Contains all of the plugin projects within the plugins/ folder
    • ga-earthsci-features - Contains all of the feature projects within the features/ folder
    • ga-earthsci-externals - Contains all of the projects within the externals/ folder

    Of course, this is just one of many groupings which may make sense for your development workflows. Feel free to setup your Eclipse workspace in any way that makes sense to you.

Running from Eclipse

The easiest way to run the application from within Eclipse is as a product, using the au.gov.ga.earthsci.product feature. Ensure you have the Plugin Developer Extensions (PDE) plugin installed.

To launch (from within Eclipse):

  1. Navigate to the au.gov.ga.earthsci.product feature (in the features/ folder)
  2. Double-click the product descriptor (au.gov.ga.earthsci.application.product). This should launch the product editor.
  3. Under the Testing section, click Synchronize configuration
  4. Then click Launch an Eclipse application

Troubleshooting

Occasionally the run configuration generated by the Eclipse tooling will not work as expected (this can be to do with including optional dependencies that introduce conflicts at runtime).

To resolve these, from the Plugins tab on the Run Configurations dialog, try deselecting all plugins and then selecting only the top-level plugins from the EarthSci RCP project before selecting Add required plugins.

If this still doesn't work, try manually selecting plugins to include.

See this FAQ section for more information: Developer-FAQ#running-the-project.

Building from Maven

The EarthSci RCP project has been configured to use the Apache Maven build management system. It uses the Eclipse Tycho plugin to use Eclipse and OSGi metadata during a Maven build. This allows you to build the plugins, features and products outside the Eclipse IDE, which is useful for CI builds etc.

Building the full product

To build the entire product suite, simply navigate to the root folder and run:

>> set MAVEN_OPTS=-Xmx2048m && mvn clean install

This will trigger a full build of every plugin and feature, and will create deployable products for each target environment. These artefacts will be installed into your local maven repository.

Note: It is recommended that a full build be conducted regularly to ensure that (a) the project still builds, and (b) that your local maven repository is regularly updated with changes. Always perform a full build before deploying a version of the application to production.

Building individual features / plugins

Each individual plugin/feature project in the EarthSci RCP project contains a POM file that references parent-pom.xml located at the root level.

Each project can be built individually using

>> mvn clean install

(or similar) from within the project folder.

Note: Building individual projects may not pick up changes to other plugins etc. if they have not been installed into your local Maven repo. It is recommended that full builds be conducted regularly (see above).

Building an executable package

Run the build.bat file, or run:

>> set MAVEN_OPTS=-Xmx2048m -XX:MaxPermSize=256m && mvn package -Dtycho.localArtifacts=ignore

Building the web start version

Before starting the build, we need to adjust the Codebase variable in the following 2 files:

  • plugins\au.gov.ga.earthsci.application\META-INF\MANIFEST.MF
  • webstart\webstart.jnlp.template

Update this to be the URL you are going to have your web start application deployed to.

Ensure JAVA_HOME is pointing at Java 8. It has been tested successfully with jdk1.8.0_45 and jdk1.8.0_131 but it might work with other builds as well.

To build the web start package, run:

build-webstart.bat <keystore_file> <keystore_alias> <keystore_password> <key_password>

This will run the above process and also sign the jar files and generate the webstart.jnlp for deployment to your web hosting.

The build-webstart.bat requires that the following arguments be provided for the jar files to be signed with your certificate, otherwise the jars will be signed with a self-signed certificate (okay for testing).

Hosting web start in S3

If you want to host your web start build in AWS S3, once the build is complete, go to the terminal and navigate to ${PROJECT_HOME}\webstart\target\webstart. From there execute the following two commands:

aws s3 cp webstart.jnlp s3://your-bucket-name/
aws s3 sync signed/ s3://your-bucket-name/signed/ --delete