Many programmers have suffered when trying to setup an environment to handle updates for their application without much effort. Some tried Java Web Start for this purpose and many encountered difficulties with this approach.

Now there is getdown that aims to replace Java Web Start by offering a simple architecture to handle updates that is fast, realiable and the only thing you need is a normal http server. Though getdown lets us handle our updates really easy it is possible to make this process even easier with the getdown maven plugin.

In the following example we’re building a simple swing application to be installed, updated and launched using getdown.

Creating an Application

First of all we need to build an application that may be updated using getdown. For this purpose and to keep it simple we’re using a swing dialog here.

This is my application:

package com.hascode.app;

import javax.swing.JFrame;
import javax.swing.JOptionPane;

public class Main {

 public static void main(final String[] args) {
 final JFrame frame = new JFrame("hasCode.com - getdown application");
 JOptionPane.showMessageDialog(frame, "getdown rocks.");
 System.exit(0);
 }

}

Running the application you should be able to see a similar output:

jframe dialog
Figure 1. Simple swing dialog.

Adding Getdown / the Getdown Maven Plugin

The following dependency adds John Oxley’s getdown maven plugin to the project – it’s using getdown 1.2 underneath (maven: com.threerings:getdown:1.2).

<plugin>
    <groupId>org.bitbucket.joxley</groupId>
    <artifactId>getdown-maven-plugin</artifactId>
    <version>0.0.1</version>
</plugin>

Now we need the getdown launcher jar available from the project website – it is used to launch the installation/update/application-run process.

For more detailed information about the concrete process, please take a look at the getdown documentation.

Configuring Getdown for the Project

The following files are important for getdown to load an application and check for updates: a configuration file named getdown.txt, a file that contains the hashes/signatures of the application and important files named digest.txt and of course the application’s jar. Luckily the maven getdown plugin generates the digest file for us so the only the we need here is the getdown.txt and if we wish so – a background image to be used for the downloader.

My getdown.txt in src/main/resources looks like this:

# The URL from which the client is downloaded
appbase = http://app.hascode.com/getdown-example/versioned

# UI Configuration
ui.name = hasCode.com Getdown Example Application
ui.background = loader-background.png

# Application jar files
code = application.jar

# The main entry point for the application
class = com.hascode.app.Main

version=1

There are several other options available but the important ones are these:

  • appbase: this is the url where you’ve uploaded your application jar, the digest and the getdown.txt

  • version: used to match against the version online (→appbase)

  • code: the application jar file

Other options used here are:

  • ui.name: this is the title that is displayed in the launcher’s app

  • ui.background: this is the file that is used as the launcher’s background image – really helpful here is the fact that the launcher’s size will be automatically adjusted to match the background image’s size.

For a full and more concise documentation of all configuration parameters, please take a look at the getdown documentation.

Deploying and Running the Application

First we need to build the application using our IDE or running..

mvn package

Afterwards there should be several files in the target directory..

target/
|-- application.jar
|-- classes
|   |-- com
|   |   `-- hascode
|   |       `-- app
|   |           `-- Main.class
|   |-- getdown.txt
|   `-- loader-background.png
|-- digest.txt
|-- getdown.txt
|-- loader-background.png
|-- maven-archiver
|   `-- pom.properties
`-- test-classes

As we can see – the digest.txt has been generated automatically .. if we wished to deploy this build as an updatable application we just needed to upload the application.jar, getdown.txt and digest.txt to a normal webserver.

We’re now able to start the application via

java -jar getdown-client-1.2.jar target/

This is what the launcher looks like without any background image defined:

download long
Figure 2. getdown updater without a background image

And this is the launcher with an background image defined (ugly but sufficient):

custom background
Figure 3. using a custom background

Finally when the download is finished our application is launched and the launcher window disappears shortly after

getdown loading app
Figure 4. application launch after successful update

In addition, getdown is able to handle user interactions such as to abort the update process

abort download
Figure 5. getdown abort installation

Testing the Update Mechanism

To test the update mechanism just create a new version and upload it to the location specified in your getdown.txt.

If you need to create a bigger file filled with some random content to simulate a bigger download – if you’re using linux or mac then dd is your friend here .. the following command creates a file with a size of 30MB..

dd if=/dev/urandom of=src/main/resources/randomfile bs=30M count=1

Logging

If an error occurs during the installation process then there is a precise log that is written by the getdown launcher in the application directory named launcher.log.

It show important details about the checksum validation, the download process and the environment – if something fails at the customer’s side – this is the file that you’ll want ;)

Tutorial Sources

I have put the source from this tutorial on my GitHub repository – download it there or check it out using Git:

git clone https://github.com/hascode/getdown-example.git

Resources