Apollo - Open Source Test Skeleton Toolkit for Java Web Start

Apollo is an open-source developer test skeleton toolkit for Web Start. Apollo lets you turbo-charge Web Start apps without Web Start to speed up your compile/run/test/debug/goof-off cycle avoiding the hassle of stuffing, signing, uploading or downloading your jars every time you rearrange a comma in your source code.

Apollo is not a replacement for Web Start (OpenJNLP, NetX or any other app launcher). Apollo is more like a test emulator (such as POSE - Palm OS Emulator) helping you to speed up your development between full-blown, time-consuming, irreplaceable, real Web Start workouts. Apollo can't fake every Web Start bell and whistle (e.g. download on demand) but outshines Sun's Web Start dumb dev pack stubs that merely let you compile your source. Apollo lets you popup your household browser and more without calling in the Web Start machinery.

Apollo consists of a jar that you can use to replace Sun's javax.jnlpx stubs residing in jnlp.jar that only allow you to compile your code and that ship with Sun's Web Start dev pack.

Apollo is a thin wrapper around Sun's javax.jnlpx services. If your app runs under Web Start Apollo will automatically detect it and pass all runtime service calls (such as poping up a browser window) on to the Web Start engine. If your app, however, runs without Web Start Apollo will kick in and mimick Web Start's runtime services.

To use Apollo replace all javax.jnlpx imports with apollo. Example:

import javax.jnlpx.*;   // Web Start only 
import apollo.*;        // Web Start plus Apollo-propelled stand-alone launching

To spare you from learning yet another API set Apollo reuses all runtime service class and method names. The only exception is Apollo's ServiceManager class that adds type-safe methods to lookup pre-defined runtime services (e.g. lookupBasicService()) avoiding unexpected runtime errors and reducing source code bloat. Example:

import javax.jnlp.*
...
BasicService bs = (BasicService) ServiceManager.lookup( "javax.jnlp.BasicService" );
bs.showDocument( new URL( "http://vamphq.com/times" ) );   

becomes

	
import apollo.*;
...
BasicService bs = ServiceManager.lookupBasicService();
bs.showDocument( new URL( "http://vamphq.com/times" ) );   

or

import apollo.*;
...
ServiceManager.lookupBasicService().showDocument( new URL( "http://vamphq.com/times" ) );   

Apollo lets you configure the codebase or the online/offline status of your app if you want to run it without Web Start but still use BasicService.getCodeBase() or Basic.isOffline().

By default BasicService.isOffline() returns false (meaning your app is online). If you want to change the setting you can pass the property apollo.offline=true to your app. As an alternative you can also add apollo.properties to your classpath or bundle it with your app's jar in the root directory. Inside the apollo.properties file add the apollo.offline property to match your desired setting. Note, that all apollo properties only work if your app runs without Web Start.

By default BasicService.getCodeBase() uses the working directory returned by the system property user.dir. To use a different codebase pass the property apollo.codebase=your_url_here to your app. As an alternative you can also add the apollo.codebase property to the apollo.properties file in your app's root directory where Apollo picks it up if you run your app without Web Start.

Apollo offers you some convenience methods (aka power methods) to spare you typing marathons or cut-and-paste orgies. For example, to create a muffin named "sticky" with the text "Apollo Rocks" using the app's codebase you can write:

MuffinStore.saveText( "sticky", "Apollo Rocks" );

Compare this with the "official" sub-atomic Web Start workout:

PersistenceService ps = (PersistenceService) 
   ServiceManager.lookup( "javax.jnlp.PersistenceService" );
BasicService bs = (BasicService)
   ServiceManager.lookup( "javax.jnlp.BasicService" );

URL baseURL = bs.getCodeBase();
URL muffinURL = new URL( baseURL, "sticky" );

ps.create( muffinURL, 1024 );

FileContents contents = ps.get( muffinURL );
DataOutputStream os = new DataOutputStream( contents.getOutputStream( true ) );
os.writeUTF( "Apollo Rocks" );
os.flush();
os.close();

To get the text for a muffin using Apollo, use the one-liner below:

String text = MuffinStore.loadText( "sticky" );

To load or save properties you can use MuffinStore.loadProperties() or MuffinStore.saveProperties().

Apollo also includes an alternative secure file chooser to clean-up Web Start's FileOpen and FileSave sandbox services. Apollo lets you write:

 
SecureFileChooser chooser = new SecureFileChooser();

if( chooser.showOpenDialog() == SecureFileChooser.CANCEL )
   return;
		    		    
FileContents contents =  chooser.getFileContents();  

instead of using the "official" cryptic Web Start calls:

FileOpenService fos = ServiceManager.lookup( "javax.jnlp.FileOpenService" );
FileContents contents = fos.openFileDialog( null, null );
if( contents == null )  // user canceled open dialog
   return;

// do your thing here

Apollo currently mimicks the following Web Start services:

• javax.jnlp.BasicService
• javax.jnlp.ClipboardService
• javax.jnlp.FileOpenService
• javax.jnlp.FileSaveService
• javax.jnlp.PersistenceService
• javax.jnlp.PrintService

That leaves only the javax.jnlp.DownloadService hanging. Also note that Apollo's FileContents interface doesn't yet support random access through the JNLPRandomAccessFile interface.

Browser Launchers

• Eric Albert's BrowserLauncher class (frozen since 2000) - http://browserlauncher.sourceforge.net
• Steven Spencer's Java World tip entitled "Control browsers from your Java application" - http://www.javaworld.com/javaworld/javatips/jw-javatip66.html

Full-fledged, open-source app launchers (aka Web Start clones)

• OpenJNLP lead by Kevin Herrboldt - http://openjnlp.nanode.org
• NetX lead by Jon A. Maxwell - http://ocd.sourceforge.net/netx/

Misc

• Mauro Marinilli's Web Start book describes a quick and dirty hack for testing Web Start runtime services without Web Start (includes a skeleton for the persistance service known as muffins). You can download the book's source at http://www.marinilli.com/books/b2/b2.html. You can download Chapter 11 entitled "Runtime Client Services" free-of-charge at Sun's dev site at http://developer.java.sun.com/developer/Books/javaprogramming/jnlp/