edu.stanford.ejalbert
Class BrowserLauncher

java.lang.Object
  extended by edu.stanford.ejalbert.BrowserLauncher

public class BrowserLauncher
extends java.lang.Object

BrowserLauncher is a class that provides a method, openURLinBrowser, which opens the default web browser for the current user of the system to the given URL. It may support other protocols depending on the system -- mailto, ftp, etc. -- but that has not been rigorously tested and is not guaranteed to work.

Yes, this is platform-specific code, and yes, it may rely on classes on certain platforms that are not part of the standard JDK. What we're trying to do, though, is to take something that's frequently desirable but inherently platform-specific -- opening a default browser -- and allow programmers (you, for example) to do so without worrying about dropping into native code or doing anything else similarly evil.

Anyway, this code is completely in Java and will run on all JDK 1.1-compliant systems without modification or a need for additional libraries. All classes that are required on certain platforms to allow this to run are dynamically loaded at runtime via reflection and, if not found, will not cause this to do anything other than returning an error when opening the browser.

There are certain system requirements for this class, as it's running through Runtime.exec(), which is Java's way of making a native system call. Currently, this requires that a Macintosh have a Finder which supports the GURL event, which is true for Mac OS 8.0 and 8.1 systems that have the Internet Scripting AppleScript dictionary installed in the Scripting Additions folder in the Extensions folder (which is installed by default as far as I know under Mac OS 8.0 and 8.1), and for all Mac OS 8.5 and later systems. On Windows, it only runs under Win32 systems (Windows 95, 98, and NT 4.0, as well as later versions of all). On other systems, this drops back from the inherently platform-sensitive concept of a default browser and simply attempts to launch Netscape via a shell command.

This code is Copyright 1999-2001 by Eric Albert (ejalbert@cs.stanford.edu) and may be redistributed or modified in any form without restrictions as long as the portion of this comment from this paragraph through the end of the comment is not removed. The author requests that he be notified of any application, applet, or other binary that makes use of this code, but that's more out of curiosity than anything and is not required. This software includes no warranty. The author is not repsonsible for any loss of data or functionality or any adverse or unexpected effects of using this software.

Credits:
Steven Spencer, JavaWorld magazine (Java Tip 66)
Thanks also to Ron B. Yeh, Eric Shapiro, Ben Engber, Paul Teitlebaum, Andrea Cantatore, Larry Barowski, Trevor Bedzek, Frank Miedrich, and Ron Rabakukk

Version:
1.0rc1
Author:
Eric Albert (ejalbert@cs.stanford.edu)

Field Summary
private  IBrowserLaunching launching
           
private  AbstractLogger logger
           
 
Constructor Summary
BrowserLauncher(AbstractLogger logger)
          Initializes the browser launcher for the operating system on which the application is running.
 
Method Summary
 java.util.List getBrowserList()
          Returns a list of browsers to be used for browser targetting.
 AbstractLogger getLogger()
          Returns the logger being used by this BrowserLauncher instance.
private  IBrowserLaunching initBrowserLauncher(AbstractLogger logger)
          Determines the operating system and loads the necessary runtime data.
static void main(java.lang.String[] args)
          Opens a browser and url from the command line.
static void openURL(java.lang.String urlString)
          Deprecated. -- create a BrowserLauncher object and use it instead of calling this static method.
 void openURLinBrowser(java.lang.String urlString)
          Attempts to open a browser and direct it to the passed url.
 void openURLinBrowser(java.lang.String browser, java.lang.String urlString)
          Attempts to open a specific browser and direct it to the passed url.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

launching

private final IBrowserLaunching launching

logger

private AbstractLogger logger
Constructor Detail

BrowserLauncher

public BrowserLauncher(AbstractLogger logger)
                throws BrowserLaunchingInitializingException,
                       UnsupportedOperatingSystemException
Initializes the browser launcher for the operating system on which the application is running.

If null is passed in as a logger, the default logger used will be NoneLogger. All log messages are ignored by this logger.

Parameters:
logger - AbstractLogger
Throws:
BrowserLaunchingInitializingException
UnsupportedOperatingSystemException
Method Detail

getLogger

public AbstractLogger getLogger()
Returns the logger being used by this BrowserLauncher instance.

Returns:
AbstractLogger

getBrowserList

public java.util.List getBrowserList()
Returns a list of browsers to be used for browser targetting. This list will always contain at least one item: BROWSER_DEFAULT.

Returns:
List
See Also:
IBrowserLaunching

initBrowserLauncher

private IBrowserLaunching initBrowserLauncher(AbstractLogger logger)
                                       throws UnsupportedOperatingSystemException,
                                              BrowserLaunchingInitializingException
Determines the operating system and loads the necessary runtime data.

If null is passed in as a logger, the default logger used will be NoneLogger. All log messages are ignored by this logger.

Parameters:
logger - AbstractLogger
Returns:
IBrowserLaunching
Throws:
UnsupportedOperatingSystemException
BrowserLaunchingInitializingException

openURLinBrowser

public void openURLinBrowser(java.lang.String urlString)
                      throws BrowserLaunchingInitializingException,
                             BrowserLaunchingExecutionException,
                             UnsupportedOperatingSystemException
Attempts to open a browser and direct it to the passed url.

Parameters:
urlString - String
Throws:
BrowserLaunchingInitializingException
BrowserLaunchingExecutionException
UnsupportedOperatingSystemException

openURLinBrowser

public void openURLinBrowser(java.lang.String browser,
                             java.lang.String urlString)
                      throws BrowserLaunchingInitializingException,
                             BrowserLaunchingExecutionException,
                             UnsupportedOperatingSystemException
Attempts to open a specific browser and direct it to the passed url. If the call to the requested browser fails, the code will fail over to the default browser.

The name for the targetted browser should come from the list returned from getBrowserList.

Parameters:
browser - String
urlString - String
Throws:
BrowserLaunchingInitializingException
BrowserLaunchingExecutionException
UnsupportedOperatingSystemException

openURL

public static void openURL(java.lang.String urlString)
                    throws UnsupportedOperatingSystemException,
                           BrowserLaunchingExecutionException,
                           BrowserLaunchingInitializingException
Deprecated. -- create a BrowserLauncher object and use it instead of calling this static method.

Attempts to open the default web browser to the given URL.

Parameters:
urlString - The URL to open
Throws:
UnsupportedOperatingSystemException
BrowserLaunchingExecutionException
BrowserLaunchingInitializingException

main

public static void main(java.lang.String[] args)
Opens a browser and url from the command line. Useful for testing. The first argument is the url to be opened. All other arguments will be ignored.

Parameters:
args - String[]