Creating updatable Java Applications using Getdown and the Getdown Maven Plugin

May 27th, 2012 by

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:

import javax.swing.JFrame;
import javax.swing.JOptionPane;
public class Main {
 public static void main(final String[] args) {
 final JFrame frame = new JFrame(" - getdown application");
 JOptionPane.showMessageDialog(frame, "getdown rocks.");

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

Simple swing dialog.

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).


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 =
# UI Configuration = Getdown Example Application
ui.background = loader-background.png
# Application jar files
code = application.jar
# The main entry point for the application
class =

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:

  • 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..

|-- application.jar
|-- classes
|   |-- com
|   |   `-- hascode
|   |       `-- app
|   |           `-- Main.class
|   |-- getdown.txt
|   `-- loader-background.png
|-- digest.txt
|-- getdown.txt
|-- loader-background.png
|-- maven-archiver
|   `--
`-- 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:

getdown updater without a background image

getdown updater without a background image

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

using a custom background

using a custom background

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

application launch after successful update

application launch after successful update

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

getdown abort installation

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


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 Bitbucket repository – download it there or check it out using Mercurial:

hg clone


Tags: , , , ,

18 Responses to “Creating updatable Java Applications using Getdown and the Getdown Maven Plugin”

  1. anon Says:

    Why won’t you stop promoting that trash named maven?

  2. micha kops Says:

    What’s your alternative, “anon”?

  3. Alexandre Verri Says:

    I don’t think that Maven is a trash. I’ve used it with great success.

    Getdown is very nice.

  4. niktwazny Says:

    gradle will kill maven in next 9 years :)
    (Git & Mercurial will kill SVN in next 5 years)

  5. micha kops Says:

    gradle is nice and has impressed me since I’ve listened to Hans Dockter’s polemic talk on the JAX Conference 2009 .. perhaps I should use it more often in my tutorials :)

    and a decade is a long time .. but maven is used quite often so perhaps your prophecy is right :)

  6. Will Says:

    Um, I cant seem to download the example?

  7. micha kops Says:

    Thanks for your remark! I’ve added a sample application in zip and tgz format.

  8. Ariel Tebez Says:

    It does not work on windows

  9. Micha Kops Says:

    Could you please state it more precisely?

  10. ventsislav Says:

    Can we update exe files with getdown. I jave my jaf file wrapped as single exe file.

  11. melvin Says:

    what is this “appbase”, is this the repository path. And how this patch working.

  12. Micha Kops Says:

    It’s the path where you’ll be uploading the artifacts … the location on your webserver..

  13. Ali Says:

    Would this mechanism work for a client-server web app which the customer installs on their own web server? Currently works using applets or Java Web Start but since both mechanisms have been deprecated we need to find another way?

  14. Micha Kops Says:

    Regard the latest changes in the Java (Oracle) Licensing you could consider bundling OpenJDK with your Application … also Getdown is still nice, but update4j seems to be worth a look, too … perhaps I could update the article to reflect this fact … see here:

  15. fholisani Says:

    How would you download or pass dynamic values in getdown.txt

  16. MadMike Says:

    Using getdown 1.8.6 the image is now:

    ui.background_image = loader-background.png

    Thanks for the little tutorial. I’d add how to run the getdown-launcher here it is:

    java -Dappbase=http:/// -jar getdown-launcher-1.8.6.jar my-app

  17. Micha Kops Says:

    Thanks for sharing this information! :)

  18. Guilherme Says:

    which would be better