JHelioviewer Development Information
From Helioviewer Wiki
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!
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.
- 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.
- lp:jhelioviewer/1.0 is the branch for releases based on the code before the Summer 09 refactoring. It is mainly for storing the stable versions of that code base. The branch is also owned by the Helioviewer developer group.
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.
The interaction between the trunk- and developer-branches follows the "Team collaboration, distributed style" approach described in the bazaar manual.
We use the Eclipse IDE with Java.
Since JHelioviewer is written in Java, a working JDK installation is essential.
- Java SE 6 Documentation contains a very useful matrix with links to Java JDK and JRE documentation etc.
- Java Web Start Guide
To remain compatible with MacOS X PPC we use Java 1.5.
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.
A recent version can be downloaded on the Eclipse download page, the "Eclipse IDE for Java Developers" package is sufficient.
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
- "Eclipse and OS X: A Natural Combination". A relatively old article, published the by Apple Developer Connection in 2004; gives an overview and contains a few useful links.
Anything special for Windows developers?
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:
Remember to do it again for EVERY new workspace.
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
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
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 2: Select Bzr from the list
Step 3: Point BzrEclipse to the (existing) bzr repository
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.
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.
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
- We use Sun's official Java Code Conventions
- 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
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
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
The sent query is saved in the normal settings property as e.g.
Adding the data
To add the data, the OberservationDialog calls the static methods from
which will send to the helioviewer.org api a query. The server address is set in the user properties as e.g.
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
Testing with delphi
So to test the new data from delphi just put into your settings at
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
JHelioviewer Code Documentation
- View Model
- Graphical User Interface (GUI)
- Writing Plug-ins for JHelioviewer Plugins for JHelioviewer
- Rendering Tries to give a overview how the rendering is triggered and processed
Building and Releasing JHV
- Describe ant targets: See README file in source tree
- TODO Website
- TODO Kakadu parts documentation