Do you hate tea which has drawn too long?

Do you like an example how to program for Java Web Start/JNLP?

A Simple Configurable Tea Timer from the Web

What you get

Here's a simple but configurable tea timer which you can use on your computer. You can change the duration, the message you get after the duration is passed and easily add (if you set another button name) or remove buttons.

What you need

The tea timer is a Java Application based on Java^TM Web Start.

To run Java Applications (at least this one) you need a Java^TM 2 JRE (Java Runtime Environment) running on your computer. If you don't have one you can download one for free from java.sun.com/j2se. It's an 8 MByte download, so you should have a sufficiently fast internet connection (and overthink whether it's worth the trouble of installing another application on your computer just for a tea timer).

Also needed is Java^TM Web Start, a new deployment technology for Java applications. If you use Java 1.4.x it's already included. Otherwise you can learn more about it on and download it from java.sun.com/products/javawebstart/.

How to start the Tea Timer

With Java Web Start

If you have both the Java Runtime Environment and Java Web Start installed, all you have to do is to click on the following link:

Start Tea Timer

If you find it useful after testing you can start it from this web page, from a link on your desktop (this may require some fiddling on Unix systems) or from the Java Web Start Application Manager. Your system will automatically download any updates (unless you have chosen otherwise).

Without Java Web Start

Okay, the Tea Timer may be run directly just as any other (Java) application if you download it and start it directly. This assumes that you have installed a Java Runtime Environment as described earlier.

I do not recommend it anyway, because every application you start on your computer (and in fact, other things like ActiveX components) has full access to your computer, i.e. they may do anything they like (e.g. hook your modem to some overseas sex number). You really should not run code from untrusted sources directly (and as you don't know me I am considered untrusted). Java Web Start runs the code in a restricted environment (called sandbox) where it may not access your harddrive and has other restrictions as well.

Still not convinced? Then just download the teatimer.jar file. If you are running Windows, you can start the tea timer by simply double clicking the file, in other envirnments call

       java -jar teatimer.jar
   

from the command line (hoping you are familiar with that).

License Agreement

The Tea Timer application found on this page may be freely used. It is not planned to be harmful in any way, furthermore the Java Web Start environment does restrict the access of unsigned applications like it (i.e. it is not allowed reading from or writing to your hard disk(s) without your explicite allowance, nor may it start connections to other computers than the one it was downloaded from, and some other restrictions). This is known as "sandbox".

On the other side no guarantee is given that it will work as provided, and there is the possiblity that flaws and bugs in itself or in interaction with other programs and parts of your computer may result in damage or harm.

More for citizens of the USA:
Drinking tea may be harmful to your health. Pouring hot tea over parts of your body will be harmful to your health. Tea and computers don't mix very well, so keep both seperated. Pouring liquids in electronic devices may cause damage to the device and electric shocks to nearby humans and animals. Putting a cat in a hot water kettle will not dry it. Reading too much legal stuff on a computer display may cause damage to your eyes and your mind.

A Simple Example How to Program For Java Web Start

What you get

The tea timer is my "Hello World!" for Java^TM Web Start (JWS). It is thought as a simple test for use of the JNLP API. If you are starting with JWS, too, you may want to have a look at the sources.

Download

Here are the complete sources of the Tea Timer. You may use them anyway you like. The JNLP file is not included, because you will need a different one for your site (or a web server on your local host, as I would recommend). If you need an example for a JNLP file, just do Save As on this link.

How to program for Java Web Start

The application is designed to work in a JWS environment as well as standalone.

All classes are in the de/caff/timer directory. Most of them don't know whether they are running standalone or under JWS. The decision is made at the beginning of the main method in the de.caff.timer.TeaTimer class.

If we are running under JWS, a de.caff.timer.JnlpPersistentDataRetriever is created to handle loading and saving of the configuration data. There you will find code how to use one of the JNLP services. Note how getCodeBase() form the BasicService is used to make the application relocatable.

Last not least direct access to resources (e.g. loading from disk) is not possible. Everything has to be read from jar files. See de.caff.timer.ShortTermTimerConfigurationWindow if you need an example how to retrieve the images shown on the up and down buttons (and stored in the images directory which is packed into the jar, too). Of course this works for standalone applications as well.

Possible Enhancements

As with all programs, there are a lot of possible enhancements. Here are some ideas which you may like to add:

• Allow the user to add images and/or sounds to the timers using a javax.jnlp.FileOpenService. Because you should only read them once (without the user asking every time he starts a timer to open the required files) and they can get quite big, you may not want to save them via PersistenceService but instead upload them to the server and create some kind of extension which can be downloaded via DownloadService.
• Start with a platform dependent look&feel instead of the default Metal. This is so simple you should make that configurable by the user to have some more fun.
• Allow for different timer views like a tradional short term timer (the ones you twist to run and which come in a lot of forms: eggs, hens etc.). A simple clock display should do for the beginning.

A possibly helpful hint for support of the JNLP MIME type

If you've read the documentation on JWS/JNLP carefully you know that your web server has to return a special MIME type for JNLP files: application/x-java-jnlp-file.

It's not always easy to convince your web space provider of changing his configuration. So if your provider runs the free Apache Web Server as many does and hasn't switched off support for the .htaccess feature (which is usually true) there's an easier way:

Just add these two lines to the .htaccess file at the top directory of your site (and just create one, if there is none):

AddType application/x-java-jnlp-file    .jnlp
AddType application/x-java-archive-diff .jardiff                                
    

Now try to load a JNLP file from your site. If you still see just the content of the file instead starting JWS be sure that you shift-click the Reload button to really circumvent any caches involved (this is at least how it works for Netscape, I don't know much of MSIE).

A note on Internationalization

If you already looked at the sources you may have wondered about the funny comments which follow many of the String constants. That is another test I made, because I tried the Java^TM Internationalization and Localization Toolkit 2.0 to convert the Tea Timer from plain English to an internationalized version (an euphemism because only English and German are supported at the moment because that's all I dare -- if you like, send me a TeaTimerRes_your-iso-language-shortcut-goes-here.java for your language).

This toolkit allows for a relative simple and straightforward way of converting from a one-language-only program to an internationalized one. It converts the code (mainly the string constants) and inserts the special comments mentioned above. After it's work is done it's easy enough to add support for further languages.