-
Notifications
You must be signed in to change notification settings - Fork 27
Getting started
This page provides a brief overview of the project, its structure, and how to obtain and build the source code.
- Overview
- Project structure
- Development environment
- Getting the source code
- Setting up in Eclipse
- Running from Eclipse
- Building from Maven
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.
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.
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 |
The following is the recommended development environment for the project.
- Java 1.8 (http://www.java.com)
- Eclipse IDE (http://www.eclipse.org/downloads/)
- Luna 4.4RC4+ (http://download.eclipse.org/eclipse/downloads/)
- Plugin Development Extensions (PDE) (http://www.eclipse.org/pde/)
- E4 Databinding (Incubation) - 0.13.0.v20140928-1736 (use E4 repository below)
- ICU4J Replacement plug-in (com.ibm.icu.base) (http://download.eclipse.org/tools/orbit/downloads/)
- Eclipse Sapphire 8.0.0 (use Sapphire repository below)
- Apache Maven 3.0.4+ (http://maven.apache.org/)
- Apache Ant (http://ant.apache.org)
- Git (http://git-scm.com/)
Repository | URL |
---|---|
E4 | http://download.eclipse.org/e4/downloads/drops/S-0.17-201501051100/repository |
Sapphire | http://download.eclipse.org/sapphire/8/repository |
- Additional Eclipse IDE plugins
- m2e (Maven integration for Eclipse)
- Internet access
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.
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:
- Navigate to https://github.com/GeoscienceAustralia/earthsci
- Click "Downloads"
- Select the format you would like to download the source code in (zip, tarball etc.)
- Extract the downloaded source code to a location of your choice
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:
- Ensure you have Git setup appropriately (see this page if you need help setting up Git)
- From a command line, cd to the directory you wish to clone the repository to
- 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).
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
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.
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.
- Within Eclipse, goto
File -> Import...
- Expand "General" folder
- Select "Existing projects into Workspace"
- Click "Next"
- Choose the
earthsci
directory as the root folder - Select all of the projects
- Click "Finish"
- 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.
Once the projects have been imported into Eclipse there are some optional steps you can perform.
-
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 theplugins/
folder -
ga-earthsci-features
- Contains all of the feature projects within thefeatures/
folder -
ga-earthsci-externals
- Contains all of the projects within theexternals/
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.
-
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.
- Navigate to the
au.gov.ga.earthsci.product
feature (in thefeatures/
folder) - Double-click the product descriptor (
au.gov.ga.earthsci.application.product
). This should launch the product editor. - Under the
Testing
section, click Synchronize configuration - Then click Launch an Eclipse application
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.
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.
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.
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).
Run the build.bat
file, or run:
>> set MAVEN_OPTS=-Xmx2048m -XX:MaxPermSize=256m && mvn package -Dtycho.localArtifacts=ignore
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).
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