CroftSoft / Library / Tutorials

Launching a Browser from Java

David Wallace Croft
Senior Software Architect
CroftSoft Inc

2001-10-23

Introduction

Java desktop applications frequently need to present the user with an online resource such as a multimedia help tutorial or an interactive web site. While Java currently supports the limited ability to display HTML using class javax.swing.JEditorPane, web browsers such as Netscape or Internet Explorer have additional advanced capabilities such as supporting HTML scripting languages and various multimedia formats. This tutorial describes how to enable your Java desktop applications to launch the default web browser on the client platform in a platform independent manner.

showDocument

Java has always supported the ability for an applet to control its browser container via the showDocument() method of interface java.applet.AppletContext.

java.applet.AppletContext.showDocument public void showDocument(java.net.URL url) Replaces the Web page currently being viewed with the given URL. This method may be ignored by applet contexts that are not browsers. Parameters: url - an absolute URL giving the location of the document.

Unfortunately, Java desktop applications, as opposed to applets, do not have access to instances of AppletContext. Recently, however, the Java Network Launching Protocol (JNLP) API has been introduced which provides an interface and method to provide a similar capability for Java applications.

javax.jnlp.BasicService.showDocument public boolean showDocument(java.net.URL url) Directs a browser on the client to show the given URL. This will typically replace the page currently being viewed in a browser with the given URL, or cause a browser to be launched that will show the given URL. Parameters: url - an URL giving the location of the document. A relative URL will be relative to the codebase. Returns: true if the request succeded, otherwise false

Reflection

Assuming a JNLP API implementation is available on the client platform, this method will automatically launch the default web browser on the client platform using code that is platform independent. Not all client platforms currently have JNLP implementations, however. For example, to my knowledge the JNLP reference implementation, Java Web Start, is currently only available on Windows, Linux, and Solaris. To give your application the flexibility to run on both client platforms with and without a JNLP implementation, you can use the Java reflection methods of package java.lang.reflect to determine whether the JNLP classes are supported on your platform and to call the showDocument() method as needed.

An instance of AppletContext is retrieved using the applet instance's own getAppletContext() method. An instance of interface BasicService, however, is retrieved using a static method, lookup() of class javax.jnlp.ServiceManager.

lookup public static java.lang.Object lookup(java.lang.String name) throws UnavailableServiceException Asks the JNLP Client for a service with a given name. The lookup must be idempotent, that is return the same object for each invocation with the same name. Parameters: name - Name of service to lookup. Returns: An object implementing the service. null will never be returned. Instead an exception will be thrown. Throws: UnavailableServiceException - if the service is not available, or if name is null.

Our first task, then, is to use reflection to invoke the lookup() method in order to retrieve an instance of interface BasicService. If this code fails, we will know that JNLP is not supported on the client platform.

private static Object getBasicServiceObject ( ) { try { Class serviceManagerClass = Class.forName ( "javax.jnlp.ServiceManager" ); Method lookupMethod = serviceManagerClass.getMethod ( "lookup", new Class [ ] { String.class } ); return lookupMethod.invoke ( null, new Object [ ] { "javax.jnlp.BasicService" } ); } catch ( Exception ex ) { return null; } }

By saving a singleton static reference to the BasicService instance retrieved, we can then use it within our own static showDocument() method. The example method returns false if JNLP is unsupported on the client platform, allowing the calling code to respond with a substitute behavior.

public static boolean showDocument ( URL url ) { if ( basicServiceObject == null ) { return false; } try { Method method = basicServiceClass.getMethod ( "showDocument", new Class [ ] { URL.class } ); Boolean resultBoolean = ( Boolean ) method.invoke ( basicServiceObject, new Object [ ] { url } ); return resultBoolean.booleanValue ( ); } catch ( Exception ex ) { ex.printStackTrace ( ); throw new RuntimeException ( ex.getMessage ( ) ); } }

The source code for a ready-to-use class implementing the above, JnlpProxy.java, is available under the terms of an Open Source license from the CroftSoft Code Library.

Resources

• Java Web Start Developer's Section

  Learn how to JNLP-enable your application at this site.

• Agoracast

  An example desktop application that responds to ad banner clicks and help documentation requests by launching a web browser using JNLP.

• CroftSoft Code Library

  An Open Source Java repository including source code for the JnlpProxy and Agoracast examples.

• com.croftsoft.core.gui.GuiCreator.createHtmlPane()

  Creates a Java Swing JEditorPane that will display an HTML document and respond to hyperlink clicks. This is a useful alternative to JNLP when you do not need the full capabilities of a sophisticated browser.

• BrowserLauncher

  An Open Source alternative to JNLP for launching a browser on multiple platforms, including Macintosh.

© 2001 CroftSoft Inc.