JHelioviewer Development Information

From Helioviewer Wiki

Jump to: navigation, search

This page gives an introduction to development in the JHelioviewer (JHV) project, most importantly describing the steps required to set up a local development environment. Since JHelioviewer (or shorter: JHV) is a part of the Helioviewer project, this document builds on the Helioviewer development introduction. The main purpose of the introduction is to get new developers started as easily as possible. If the described setup doesn't work, you have open questions, etc., please let us know!

Contents

Project Overview

JHelioviewer is the main local viewing client in the Helioviewer project. A description of the project can be found on the JHelioviewer main page.

Version Control System

The JHV code base is organized into several branches. Since trunk revision 17, every branch represents a workspace in eclipse, including several projects. There exists a general ant build file build.xml which must be called with ant precompile or higher task before importing into Eclipse.

To ensure a proper merging and to not include trivial changes, the Eclipse Java formatter must be called before each committing.

Main branches

  • lp:jhelioviewer is the main development branch for JHV, containing the latest version of the code. The purpose of this branch is to share completed features and bug fixes that are relevant to all developers but aren't tied to any release or extensive testing. Moreover it is the main branch all other Helioviewer Java branches are originating from. In order to make sure that all Helioviewer developers can contribute to this branch, it is owned by the Helioviewer developer group on launchpad. The branch is associated with the trunk series.
  • lp:jhelioviewer/2.0 is the branch for releases based on the code after the refactoring during summer 09. This branch is intended to include all the versions of JHV we are going to release. The corresponding series is 2.0. We should only package code from this branch so that it's later easy to find the corresponding version. The branch is also owned by the Helioviewer developer group.

Developer branches

Each developer has at least one personal branch for day-to-day development of features, bug fixes, etc.. Having several personal branches to separate the development of different features is possible and considered good practice. It is a good idea to host the more important local branches on launchpad and push them regularly. This gives others an idea what each team member is currently working on and is an easy back-up of local changes.

A list of developer branches can be found on the Launchpad JHelioviewer code page.

Workflow

The interaction between the trunk- and developer-branches follows the "Team collaboration, distributed style" approach described in the bazaar manual.

Development Environment

We use the Eclipse IDE with Java.

Java

Since JHelioviewer is written in Java, a working JDK installation is essential.

To remain compatible with MacOS X PPC we use Java 1.5.

Linux

At the moment, JHV supports only the Java distribution from Sun. The corresponding Debian package is sun-java6-jdk.

-- Helge: I think IcedTea, the open source version, does now work by default.

Mac OS X

Mac OS X ships with Java. Keep in mind that for Macs with PowerPC architecture, only Java 1.5 is available from Apple. Thus, if you want to run JHelioviewer on a PowerPC Mac, make sure the jar file has been generated using Java 1.5. So far (April 2010), the JHelioviewer code only uses Java 1.5, and published jar files have been generated on a PowerPC Mac to ensure cross-version compatibility.

Windows

Download the latest Java version here.


Installing Eclipse

A recent version can be downloaded on the Eclipse download page, the "Eclipse IDE for Java Developers" package is sufficient.

Linux

Debian and Ubuntu users should be aware that the version of Eclipse currently found in the official repositories is outdated. It is recommended to download the binary package (either 32 bit or 64 bit) from the Eclipse download page. The executable file contained in the archive can simply be started to launch Eclipse. No compilation or installation process is necessary, all internal Eclipse files remain in the directory the program is extracted to.

Mac OS X

Windows

Anything special for Windows developers?

Configuring Eclipse

If you are using workspace mechanic, skip this section.

First set the formatter as Formatting. Secondly set the editor preference to insert space instead of tab and use 4 space per tab.

For that go to Eclipse->Preferences and search for tab:

EclipseEditorTabPreferences.png

Remember to do it again for EVERY new workspace.

Workspace Mechanic

To ensure that the formatter and tab setting are consistent in each commit, we use workspacemechanic from: http://code.google.com/a/eclipselabs.org/p/workspacemechanic/

For a quick start, just go to "Help->Install New Software..." and select the site: http://workspacemechanic.eclipselabs.org.codespot.com/hg.update/mechanic After following the instruction and selecting Workspace Mechanic it will be installed for your eclipse installation.

The used settings are in mechanic of the repository:

  • tab_space.epf - Setting tab to four space
  • formatter.epf - Sets the java formatter

To use them just copy the files to ~/.eclipse/mechanic and the settings will be checked at the next startup. You can also use install.sh which does the job

BUGS/PROBLEMS Setting the formatter options such that format will yield the right result is properly done, see formatter.epf how to create the settings. However, editing the gui for the selection properly, is not working at the moment and I have no idea how to do it. So after applying the settings it should work out of the box and just the preference dialog seems outdated. Maybe worth checking some more recent version in some time. -- Helge Dietert

BzrEclipse

When using Eclipse's refactoring functionality it often comes to problems when filenames are automatically changed. In these cases, bzr cannot relate the renamed filenames to their old, versioned, original filenames. If renaming is not done using "bzr mv", future merges of files will not work properly. In order to let Eclipse automatically instruct bzr to move the files, we suggest to use the BzrEclipse plugin.

Installation instructions can be found at http://wiki.bazaar.canonical.com/BzrEclipse/Installation

After having installed BzrEclipse, make sure that all projects are properly connected to their bzr repositories. The following steps show you how to achieve this:

Step 1: Right-Click the project(s) in question and select 'Team - Share Project'

BzrEclipseShareProject.png

Step 2: Select Bzr from the list

ShareProjectWithBzr.png

Step 3: Point BzrEclipse to the (existing) bzr repository

PointToBzrExecutable.png

Additional: Activate status overlays

It might be useful to activate the bzr status overlays. Go to the Eclipse's Properties and activate the bzr status decorators.

EnableBzrDecoratos.png


Importing a branch into Eclipse and run JHelioviewer

To open the branch, start Eclipse (see details below) and switch the workspace to the folder of your branch. Right-click in Package Explorer panel on the left and choose the following in the context menu: Import... -> Existing Projects into Workspace, browse to the workspace folder and import all projects found. To start JHelioviewer, launch the project "jhv" as a Java application. To avoid running out of Java heap space, it is useful to increase the maximum heap space available: In the Package Explorer panel, right-click on "jhv", then choose Run as->Run configurations... Under Java Applications->JavaHelioViewer, you will find the tab "Arguments". In this tab, enter "-Xmx1500m" in the "VM arguments" box.

JHV Eclipse RunConfig.png

To debug JHelioviewer just lauch JavaHelioViewer.java from jhv. Please note, that this does not include the automatic Java heap space setting.

JHelioviewer Development Guidelines

While programming:

  • Always work on the code in your own branch
  • Use speaking names (e.g. no variables consisting of just one character)
  • Discuss with others, if possible
  • Use comments
  • Respect code style
  • All functions and variable should be spelled correctly
  • Think about the best way of implementing a feature long enough
  • See related classes to stay consistent
  • Stay modular
  • Do not rely on implementation-specific details of other classes as they might change; only use the defined interface
  • Commit to your own branch often
  • When committing, make sure to add new files to the version control ("bzr add <file>")

Checklist before merging changes into trunk:

  • No errors left in code
  • No warnings left in code
  • No auto-generated TODOs left in code
  • No unnecessary use of System.out
  • All classes and functions have correct and accurate Javadocs commentaries
  • Normal comments should be placed where necessary
  • Test new features extensively, including unexpected and wrong inputs
  • After testing, show new features to supervisor and get approval before moving new features into trunk

JHelioviewer Architecture

What data can I choose and where does it come from

With the remote dialog you can always choose any data directly from any server as you like.

Here it will describe the flow of information to add something through the GUI

Setting up the gui

The "AddLayer" Button opens the control panel org.helioviewer.jhv.gui.dialogs.ObservationDialog. This class gathers the information from org.helioviewer.jhv.io.DataSources which is designed as singleton instance and will acquire the information from the server on the first start up.

At the moment it is just used to setup the dropdown lists but further options seems possible, like layering information or different servers which the ObservationDialog could also acquire from the DataSource object or some other logic.

The shown data sources are just the JSON results of the Helioviewer.org API getDataSources. The sent query is saved in the normal settings property as e.g. API.dataSources.path=http\://helioviewer.nascom.nasa.gov/api/?action=getDataSources.

Adding the data

To add the data, the OberservationDialog calls the static methods from org.helioviewer.jhv.io.APIRequestManager which will send to the helioviewer.org api a query. The server address is set in the user properties as e.g. API.jp2series.path and API.jp2images.path.

From the result the uri property is read and if its not null it will be tried to load. If message is set, the message will be shown. If uri is null, this means the server could not provide any data, so if set we show message or some general error message.

Testing with delphi

So to test the new data from delphi just put into your settings at ~/JHelioviewer/Settings/user.properties the following settings:

API.jp2images.path=http\://delphi.nascom.nasa.gov/api/index.php
API.jp2series.path=http\://delphi.nascom.nasa.gov/api/index.php
API.dataSources.path=http\://delphi.nascom.nasa.gov/api/?action\=getDataSources&verbose\=true

JPIP Server

JHelioviewer Code Documentation

Code Architecture

Testing

External links

Building and Releasing JHV

  • Describe ant targets: See README file in source tree
  • TODO Website
  • TODO Kakadu parts documentation
buy lasix online
Personal tools