org.moyoman.client.reference.util
Class BrowserLauncher

java.lang.Object
  |
  +--org.moyoman.client.reference.util.BrowserLauncher

public class BrowserLauncher

extends Object

BrowserLauncher is a class that provides one static method, openURL, 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-2002 by Eric Albert (ejalbert AT 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, Ron Rabakukk, and Glenn Vanderburg

Version:

1.6

Author:

Eric Albert (ejalbert AT cs.stanford.edu)

Field Summary

private static List	_linuxBrowsers Collection of Linux browser commands, in order of preference.
private static Class	aeDescClass The com.apple.MacOS.AEDesc class
private static Constructor	aeDescConstructor The <init>(String) method of com.apple.MacOS.AEDesc
private static Constructor	aeTargetConstructor The <init>(int) method of com.apple.MacOS.AETarget
private static Constructor	appleEventConstructor The <init>(int, int, int) method of com.apple.MacOS.AppleEvent
private static Object	browser The browser for the system
private static String	errorMessage The message from any exception thrown throughout the initialization process.
private static String	FINDER_CREATOR The creator code of the Finder on a Macintosh, which is needed to send AppleEvents to the application.
private static String	FINDER_TYPE The file type of the Finder on a Macintosh.
private static Method	findFolder The findFolder method of com.apple.mrj.MRJFileUtils
private static String	FIRST_WINDOWS_PARAMETER The first parameter that needs to be passed into Runtime.exec() to open the default web browser on Windows.
private static Method	getFileCreator The getFileCreator method of com.apple.mrj.MRJFileUtils
private static Method	getFileType The getFileType method of com.apple.mrj.MRJFileUtils
private static String	GURL_EVENT The name for the AppleEvent type corresponding to a GetURL event.
private static String	JDirect_MacOSX The framework to reference on Mac OS X 10.0.x
private static int	jvm The Java virtual machine that we are running on.
private static Integer	kAnyTransactionID The kAnyTransactionID AppleEvent code
private static Integer	kAutoGenerateReturnID The kAutoGenerateReturnID AppleEvent code
private static Integer	keyDirectObject The keyDirectObject AppleEvent parameter type
private static Object	kSystemFolderType Actually an MRJOSType pointing to the System Folder on a Macintosh
private static Object	linkage The linkage object required for JDirect 3 on Mac OS X
private static int	LINUX JVM constant for Linux.
private static boolean	loadedWithoutErrors Caches whether any classes, methods, and fields that are not part of the JDK and need to be dynamically loaded at runtime loaded successfully.
private static Method	makeOSType The makeOSType method of com.apple.MacOS.OSUtils
private static int	MRJ_2_0 JVM constant for MRJ 2.0
private static int	MRJ_2_1 JVM constant for MRJ 2.1.x and 2.2.x
private static int	MRJ_3_0 JVM constant for Java on Mac OS X 10.0 (MRJ 3.0)
private static int	MRJ_3_1 JVM constant for Java 1.3.x on Mac OS X 10.1 and later (MRJ 3.1 and 3.2)
private static int	MRJ_COCOA JVM constant for Java 1.4.x and later on Mac OS X
private static Class	mrjFileUtilsClass The com.apple.mrj.MRJFileUtils class
private static Class	mrjOSTypeClass The com.apple.mrj.MRJOSType class
private static String	NETSCAPE_OPEN_PARAMETER_END
private static String	NETSCAPE_OPEN_PARAMETER_START
private static String	NETSCAPE_REMOTE_PARAMETER The shell parameters for Netscape that opens a given URL in an already-open copy of Netscape on many command-line systems.
private static Method	openURL The openURL method of com.apple.mrj.MRJFileUtils
private static int	OTHER JVM constant for any other platform
private static Method	putParameter The putParameter method of com.apple.MacOS.AppleEvent
private static String	SECOND_WINDOWS_PARAMETER The second parameter for Runtime.exec() on Windows.
private static Method	sendNoReply The sendNoReply method of com.apple.MacOS.AppleEvent
private static String	THIRD_WINDOWS_PARAMETER The third parameter for Runtime.exec() on Windows.
private static int	WINDOWS_9x JVM constant for any Windows 9x JVM
private static int	WINDOWS_NT JVM constant for any Windows NT JVM

Constructor Summary

private

BrowserLauncher() This class should be never be instantiated; this just ensures so.

Method Summary

private static String	getEnvironmentBrowser() Tries to read the BROWSER environment variable, which should be set to the absolute path of the user's preferred web browser as proposed at http://tuxedo.org/~esr/BROWSER.
private static int	ICLaunchURL(int instance, byte[] hint, byte[] data, int len, int[] selectionStart, int[] selectionEnd)
private static int	ICStart(int[] instance, int signature) Methods required for Mac OS X 10.0.x.
private static int	ICStop(int[] instance)
private static boolean	loadClasses() Called by a static initializer to load any classes, fields, and methods required at runtime to locate the user's web browser.
private static boolean	loadMRJ20Classes() Loads the classes, fields, and methods needed when running under MRJ 2.0.
private static Object	locateBrowser() Attempts to locate the default web browser on the local system.
static void	openURL(String url) Attempts to open the default web browser to the given URL.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

jvm

private static int jvm

The Java virtual machine that we are running on. Actually, in most cases we only care about the operating system, but some operating systems require us to switch on the VM.

browser

private static Object browser

The browser for the system

loadedWithoutErrors

private static boolean loadedWithoutErrors

Caches whether any classes, methods, and fields that are not part of the JDK and need to be dynamically loaded at runtime loaded successfully.

Note that if this is false, openURL() will always return an IOException.

mrjFileUtilsClass

private static Class mrjFileUtilsClass

The com.apple.mrj.MRJFileUtils class

mrjOSTypeClass

private static Class mrjOSTypeClass

The com.apple.mrj.MRJOSType class

aeDescClass

private static Class aeDescClass

The com.apple.MacOS.AEDesc class

aeTargetConstructor

private static Constructor aeTargetConstructor

The <init>(int) method of com.apple.MacOS.AETarget

appleEventConstructor

private static Constructor appleEventConstructor

The <init>(int, int, int) method of com.apple.MacOS.AppleEvent

aeDescConstructor

private static Constructor aeDescConstructor

The <init>(String) method of com.apple.MacOS.AEDesc

findFolder

private static Method findFolder

The findFolder method of com.apple.mrj.MRJFileUtils

getFileCreator

private static Method getFileCreator

The getFileCreator method of com.apple.mrj.MRJFileUtils

getFileType

private static Method getFileType

The getFileType method of com.apple.mrj.MRJFileUtils

openURL

private static Method openURL

The openURL method of com.apple.mrj.MRJFileUtils

makeOSType

private static Method makeOSType

The makeOSType method of com.apple.MacOS.OSUtils

putParameter

private static Method putParameter

The putParameter method of com.apple.MacOS.AppleEvent

sendNoReply

private static Method sendNoReply

The sendNoReply method of com.apple.MacOS.AppleEvent

kSystemFolderType

private static Object kSystemFolderType

Actually an MRJOSType pointing to the System Folder on a Macintosh

keyDirectObject

private static Integer keyDirectObject

The keyDirectObject AppleEvent parameter type

kAutoGenerateReturnID

private static Integer kAutoGenerateReturnID

The kAutoGenerateReturnID AppleEvent code

kAnyTransactionID

private static Integer kAnyTransactionID

The kAnyTransactionID AppleEvent code

linkage

private static Object linkage

The linkage object required for JDirect 3 on Mac OS X

_linuxBrowsers

private static List _linuxBrowsers

Collection of Linux browser commands, in order of preference.

LINUX

private static final int LINUX

JVM constant for Linux.

See Also:

Constant Field Values

JDirect_MacOSX

private static final String JDirect_MacOSX

The framework to reference on Mac OS X 10.0.x

See Also:

Constant Field Values

MRJ_2_0

private static final int MRJ_2_0

JVM constant for MRJ 2.0

See Also:

Constant Field Values

MRJ_2_1

private static final int MRJ_2_1

JVM constant for MRJ 2.1.x and 2.2.x

See Also:

Constant Field Values

MRJ_3_0

private static final int MRJ_3_0

JVM constant for Java on Mac OS X 10.0 (MRJ 3.0)

See Also:

Constant Field Values

MRJ_3_1

private static final int MRJ_3_1

JVM constant for Java 1.3.x on Mac OS X 10.1 and later (MRJ 3.1 and 3.2)

See Also:

Constant Field Values

MRJ_COCOA

private static final int MRJ_COCOA

JVM constant for Java 1.4.x and later on Mac OS X

See Also:

Constant Field Values

WINDOWS_NT

private static final int WINDOWS_NT

JVM constant for any Windows NT JVM

See Also:

Constant Field Values

WINDOWS_9x

private static final int WINDOWS_9x

JVM constant for any Windows 9x JVM

See Also:

Constant Field Values

OTHER

private static final int OTHER

JVM constant for any other platform

See Also:

Constant Field Values

FINDER_TYPE

private static final String FINDER_TYPE

The file type of the Finder on a Macintosh. Hardcoding "Finder" would keep non-U.S. English systems from working properly.

See Also:

Constant Field Values

FINDER_CREATOR

private static final String FINDER_CREATOR

The creator code of the Finder on a Macintosh, which is needed to send AppleEvents to the application.

See Also:

Constant Field Values

GURL_EVENT

private static final String GURL_EVENT

The name for the AppleEvent type corresponding to a GetURL event.

See Also:

Constant Field Values

FIRST_WINDOWS_PARAMETER

private static final String FIRST_WINDOWS_PARAMETER

The first parameter that needs to be passed into Runtime.exec() to open the default web browser on Windows.

See Also:

Constant Field Values

SECOND_WINDOWS_PARAMETER

private static final String SECOND_WINDOWS_PARAMETER

The second parameter for Runtime.exec() on Windows.

See Also:

Constant Field Values

THIRD_WINDOWS_PARAMETER

private static final String THIRD_WINDOWS_PARAMETER

The third parameter for Runtime.exec() on Windows. This is a "title" parameter that the command line expects. Setting this parameter allows URLs containing spaces to work.

See Also:

Constant Field Values

NETSCAPE_REMOTE_PARAMETER

private static final String NETSCAPE_REMOTE_PARAMETER

The shell parameters for Netscape that opens a given URL in an already-open copy of Netscape on many command-line systems.

See Also:

Constant Field Values

NETSCAPE_OPEN_PARAMETER_START

private static final String NETSCAPE_OPEN_PARAMETER_START

See Also:

Constant Field Values

NETSCAPE_OPEN_PARAMETER_END

private static final String NETSCAPE_OPEN_PARAMETER_END

See Also:

Constant Field Values

errorMessage

private static String errorMessage

The message from any exception thrown throughout the initialization process.

Constructor Detail

BrowserLauncher

private BrowserLauncher()

This class should be never be instantiated; this just ensures so.

Method Detail

openURL

public static void openURL(String url)
                    throws IOException

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

Parameters:

url - The URL to open

Throws:

IOException - If the web browser could not be located or does not run

getEnvironmentBrowser

private static String getEnvironmentBrowser()

Tries to read the BROWSER environment variable, which should be set to the absolute path of the user's preferred web browser as proposed at http://tuxedo.org/~esr/BROWSER.

Returns:

The value of the BROWSER environment variable, or null if the variable does not exist or can't be read.

ICLaunchURL

private static int ICLaunchURL(int instance,
                               byte[] hint,
                               byte[] data,
                               int len,
                               int[] selectionStart,
                               int[] selectionEnd)

ICStart

private static int ICStart(int[] instance,
                           int signature)

Methods required for Mac OS X 10.0.x. The presence of native methods does not cause any problems on other platforms.

ICStop

private static int ICStop(int[] instance)

loadClasses

private static boolean loadClasses()

Called by a static initializer to load any classes, fields, and methods required at runtime to locate the user's web browser.

Returns:

true if all intialization succeeded false if any portion of the initialization failed

loadMRJ20Classes

private static boolean loadMRJ20Classes()

Loads the classes, fields, and methods needed when running under MRJ 2.0. Sets errorMessage if it fails.

Returns:

true if all operations succeeded; false otherwise

locateBrowser

private static Object locateBrowser()

Attempts to locate the default web browser on the local system. Caches the result so it only locates the browser once for each use of this class per JVM instance.

Returns:

The browser for the system. Note that this may not be what you would consider to be a standard web browser; instead, it's the application that gets called to open the default web browser. In some cases this will be a non-String object that provides the means of calling the default browser.