Rachel - Resource Loading for Java Web Start Made Easy

Rachel is an open-source resource loading toolkit for Java Web Start/JNLP. Rachel offers two solutions that make resource loading for Java Web Start/JNLP apps easy again.

• Solution 1 installs a URL handler for a new protocoll called class:// that delivers content from your app's jars identified by a Java class.
• Solution 2 embeds a multi-threaded, ultra-lightweight Web server in your app that serves up content for your app's jars using plain-vanilla http:// URLs.

Note, that Rachel also works without Java Web Start, although this might be pointless.

Hello Rachel - Java Web Start Resource Loading Demo App Powered By Rachel.

• Browse the Source
• Kick Start Hello Rachel App

Rachel is an open-source resource loading toolkit for Java Web Start making resource loading easy again. Rachel takes you on a higher plane as you no longer need to use low-level, sub-atomic, complex ClassLoader trickery as illustrated by the code snippet below taken from Sun's Java Web Start Developer's Guide :

// Get current classloader
ClassLoader cl = this.getClass().getClassLoader();
// Create icons
Icon saveIcon = new ImageIcon( cl.getResource( "images/save.gif" ));
Icon cutIcon  = new ImageIcon( cl.getResource( "images/cut.gif" ));

Why all this messing around with ClassLoader's and getResource? Isn't there a simpler way? Why is resource loading so hard for JavaWebStart software in the first place? What's the deal? How are Java Web Start application different from plain-vanilla Java desktop applications?

Here is the essence extracted from the Application Development Considerations section in Sun's Java Web Start Developer's Guide to justify this code:

Rule 1: Java Archives only. No loose files. All your resources have to be packaged in Java Archives (jar) if you want to have them delivered to the user's machine and kept up-to-date automatically by Java Web Start.

Rule 2: No file paths. You can't use absolute or relative file paths to locate your jars holding your resources (e.g. jar:file:///c:/java/jws/.cache/resources.jar). Absolute file paths won't work because you never know where Java Web Start will put your jar on the user's machine. Relative file paths won't work because Java Web Start mangles the names of your jars (e.g. venus.jar becomes RMvenus.jar) and every JNLP client implementation has the right to mangle your names in a different way and you, therefore, can't predict the name with which your jar will be rechristend and end up on the user's machine in the application cache.

One Solution. No. Two Solutions.

Rachel offers two solutions that make resource loading easy again. You won't miss the old plain-vanilla Java days as Java Web Start now also automatically up-dates your resources along with your class files.

Solution 1 installs a URL handler for a new protocol called class:// that delivers content from jars identified by a Java class. Example:

class://ThemeAnchor/skinlf/themes/modern.zip

The Java class ThemeAnchor identifies the Java Archive themes.jar in the example above. There is no need to use absolute or relative file paths to identify jars. The fully qualified name of a single Java class in the jar is sufficient to find it in the application cache. To clear things up, here is the content of themes.jar which is part of the example application shipped with Rachel:

skinlf/themes/modern.zip
images/world2.gif
images/inform.gif
META-INF/Manifest.mf
ThemeAnchor.class

Once the URL handler is installed, resources can be loaded using the standard java.net.URL class. Example:

URL appIconUrl = new URL( "class://ThemeAnchor/images/inform.gif );
ImageIcon appIcon = new ImageIcon( appIconUrl );

Solution 2 embeds a multi-threaded ultra light-weight web server in your app that serves up content from jars in the Java Web Start cache. Your end-users can also access your resources (such as HTML documents) through external browsers using standard web addresses (e.g. http://localhost:5454/crossref/index.html) as long as your application is up and running (or the document lingers on in the browser's cache).

---

Method 1: Use class:// URL handler

To use a URL using the new protocol class:// that delivers content from jars follow these steps:

Step 1: Register a new URL handler for the class:// protocol

Example:

URL.setURLStreamHandlerFactory( new VampUrlFactory() );

Step 2: Create a URL using the class:// protocol for the resource you want to retrieve from a jar

Use the following syntax when you create a URL for the class:// protocol:

class://<class>/<path>

Examples:

class://venus.Tool/images/powered-by-velocity.gif
class://Chrome/skinlf/themes/aqua.zip
class://JavaDocAnchor/javadoc/index.html
class://ThemeAnchor/images/world2.gif

Step 3: Get resource using java.net.URL

To get a resource (e.g. an image, HTML document or theme pack) you can use Java's standard java.net.URL class. Example:

URL appIconUrl = new URL( "class://ThemeAnchor/images/inform.gif" );
ImageIcon appIcon =  new ImageIcon( appIconUrl );

or

URL themepack = new URL( "class://ThemeAnchor/skinlf/themes/modern.zip" );
Skin skin = SkinLookAndFeel.loadThemePack( themepack );

Tip: You can use this method to serve up HTML pages from any jar in your internal web browser (aka JEditorPane). Example:

URL crossRefUrl = new URL( "class://CrossRefAnchor/crossref/index.html" );
JEditorPane browser = new JEditorPane();
browser.setEditable( false );
browser.setContentType( "text/html" );
browser.setPage( crossRefUrl );

---

Method 2: Embed a multi-threaded, ultra light-weight web server into your app

To use Rachel's embedded multi-threaded ultra light-weight web server that serves up content from jars follow these steps:

Step 1: Package all your resources (documents, graphics, etc.) in a jar.

Step 2: Add an anchor class to every jar from which you want to retrieve your resources so that the embedded web server can find your resources.

Example:

public class CrossRefAnchor
{
  public CrossRefAnchor() {}
}

Yes, that's it. The class is just here to identify the Java Archive. There is no need to calculate a random seed for your digital certificate or to burn the weather report on your toast.

Step 3: Add a ClassResourceLoader to WebResourceManager for every jar from which you want to retrieve resources

Example:

WebResourceManager roots = WebResourceManager.getInstance();
roots.addResourceLoader( new ClassResourceLoader( CrossRefAnchor.class ) );
roots.addResourceLoader( new ClassResourceLoader( JavaDocAnchor.class ) );

Step 4: Startup the multi-threaded ultra light-weight web server

Example:

try
{
  WebServer http = new WebServer( 7272, roots );
  http.start();
}
catch( IOException ioex )
{
  T.error( "*** failed to start http service: " + ioex.toString() );
}

Step 5: You are ready to roll. Display page in external or internal browser as you desire as Rachel is at your service.

Example:

URL crossRefUrl = new URL( "http://localhost:7272/crossref/index.html" );
JEditorPane browser = new JEditorPane();
browser.setEditable( false );
browser.setContentType( "text/html" );
browser.setPage( crossRefUrl );