cern::laser::guiplatform::util::BrowserLauncher Class Reference

Collaboration diagram for cern::laser::guiplatform::util::BrowserLauncher:

Static Public Member Functions
static void	openURL (String url) throws IOException
Static Package Functions
	[static initializer]
Private Member Functions
	BrowserLauncher ()
Static Private Member Functions
static boolean	loadClasses ()
static Object	locateBrowser ()
static native int	ICStart (int[] instance, int signature)
static native int	ICStop (int[] instance)
static native int	ICLaunchURL (int instance, byte[] hint, byte[] data, int len, int[] selectionStart, int[] selectionEnd)
Static Private Attributes
static int	jvm
static Object	browser
static boolean	loadedWithoutErrors
static Class	mrjFileUtilsClass
static Class	mrjOSTypeClass
static Class	aeDescClass
static Constructor	aeTargetConstructor
static Constructor	appleEventConstructor
static Constructor	aeDescConstructor
static Method	findFolder
static Method	getFileCreator
static Method	getFileType
static Method	openURL
static Method	makeOSType
static Method	putParameter
static Method	sendNoReply
static Object	kSystemFolderType
static Integer	keyDirectObject
static Integer	kAutoGenerateReturnID
static Integer	kAnyTransactionID
static Object	linkage
static final String	JDirect_MacOSX = "/System/Library/Frameworks/Carbon.framework/Frameworks/HIToolbox.framework/HIToolbox"
static final int	MRJ_2_0 = 0
static final int	MRJ_2_1 = 1
static final int	MRJ_3_0 = 3
static final int	MRJ_3_1 = 4
static final int	WINDOWS_NT = 5
static final int	WINDOWS_9x = 6
static final int	OTHER = -1
static final String	FINDER_TYPE = "FNDR"
static final String	FINDER_CREATOR = "MACS"
static final String	GURL_EVENT = "GURL"
static final String	FIRST_WINDOWS_PARAMETER = "/c"
static final String	SECOND_WINDOWS_PARAMETER = "start"
static final String	THIRD_WINDOWS_PARAMETER = "\"\""
static final String	NETSCAPE_REMOTE_PARAMETER = "-remote"
static final String	NETSCAPE_OPEN_PARAMETER_START = "'openURL("
static final String	NETSCAPE_OPEN_PARAMETER_END = ")'"
static String	errorMessage

Detailed Description

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-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

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

Version:: 1.4b1 (Released June 20, 2001)

Constructor & Destructor Documentation

cern::laser::guiplatform::util::BrowserLauncher::BrowserLauncher ( ) [inline, private]

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

Member Function Documentation

cern::laser::guiplatform::util::BrowserLauncher::[static initializer] ( ) [inline, static, package]

An initialization block that determines the operating system and loads the necessary runtime data.

static native int cern::laser::guiplatform::util::BrowserLauncher::ICLaunchURL	(	int	instance,
		byte[]	hint,
		byte[]	data,
		int	len,
		int[]	selectionStart,
		int[]	selectionEnd
	)			`[static, private]`

static native int cern::laser::guiplatform::util::BrowserLauncher::ICStart	(	int[]	instance,
		int	signature
	)			`[static, private]`

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

static native int cern::laser::guiplatform::util::BrowserLauncher::ICStop ( int[] instance ) [static, private]

static boolean cern::laser::guiplatform::util::BrowserLauncher::loadClasses ( ) [inline, static, private]

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

References aeDescClass, aeDescConstructor, aeTargetConstructor, appleEventConstructor, errorMessage, findFolder, getFileCreator, getFileType, jvm, kAnyTransactionID, kAutoGenerateReturnID, keyDirectObject, kSystemFolderType, linkage, makeOSType, MRJ_2_0, MRJ_2_1, MRJ_3_0, MRJ_3_1, mrjFileUtilsClass, mrjOSTypeClass, openURL, putParameter, and sendNoReply.

static Object cern::laser::guiplatform::util::BrowserLauncher::locateBrowser ( ) [inline, static, private]

Attempts to locate the default web browser on the local system. Caches results 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.

References aeTargetConstructor, appleEventConstructor, browser, FINDER_CREATOR, GURL_EVENT, jvm, kAnyTransactionID, kAutoGenerateReturnID, makeOSType, and MRJ_2_0.

static void cern::laser::guiplatform::util::BrowserLauncher::openURL ( String url ) throws IOException [inline, static]

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

Parameters:

url

The URL to open

Exceptions:

IOException

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

Member Data Documentation

Class cern::laser::guiplatform::util::BrowserLauncher::aeDescClass [static, private]

The com.apple.MacOS.AEDesc class

Referenced by loadClasses().

Constructor cern::laser::guiplatform::util::BrowserLauncher::aeDescConstructor [static, private]

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

Referenced by loadClasses().

Constructor cern::laser::guiplatform::util::BrowserLauncher::aeTargetConstructor [static, private]

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

Referenced by loadClasses(), and locateBrowser().

Constructor cern::laser::guiplatform::util::BrowserLauncher::appleEventConstructor [static, private]

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

Referenced by loadClasses(), and locateBrowser().

Object cern::laser::guiplatform::util::BrowserLauncher::browser [static, private]

The browser for the system

Referenced by locateBrowser().

String cern::laser::guiplatform::util::BrowserLauncher::errorMessage [static, private]

The message from any exception thrown throughout the initialization process.

Referenced by loadClasses().

final String cern::laser::guiplatform::util::BrowserLauncher::FINDER_CREATOR = "MACS" [static, private]

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

Referenced by locateBrowser().

final String cern::laser::guiplatform::util::BrowserLauncher::FINDER_TYPE = "FNDR" [static, private]

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

Method cern::laser::guiplatform::util::BrowserLauncher::findFolder [static, private]

The findFolder method of com.apple.mrj.MRJFileUtils

Referenced by loadClasses().

final String cern::laser::guiplatform::util::BrowserLauncher::FIRST_WINDOWS_PARAMETER = "/c" [static, private]

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

Method cern::laser::guiplatform::util::BrowserLauncher::getFileCreator [static, private]

The getFileCreator method of com.apple.mrj.MRJFileUtils

Referenced by loadClasses().

Method cern::laser::guiplatform::util::BrowserLauncher::getFileType [static, private]

The getFileType method of com.apple.mrj.MRJFileUtils

Referenced by loadClasses().

final String cern::laser::guiplatform::util::BrowserLauncher::GURL_EVENT = "GURL" [static, private]

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

Referenced by locateBrowser().

final String cern::laser::guiplatform::util::BrowserLauncher::JDirect_MacOSX = "/System/Library/Frameworks/Carbon.framework/Frameworks/HIToolbox.framework/HIToolbox" [static, private]

The framework to reference on Mac OS X

int cern::laser::guiplatform::util::BrowserLauncher::jvm [static, private]

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.

Referenced by loadClasses(), and locateBrowser().

Integer cern::laser::guiplatform::util::BrowserLauncher::kAnyTransactionID [static, private]

The kAnyTransactionID AppleEvent code

Referenced by loadClasses(), and locateBrowser().

Integer cern::laser::guiplatform::util::BrowserLauncher::kAutoGenerateReturnID [static, private]

The kAutoGenerateReturnID AppleEvent code

Referenced by loadClasses(), and locateBrowser().

Integer cern::laser::guiplatform::util::BrowserLauncher::keyDirectObject [static, private]

The keyDirectObject AppleEvent parameter type

Referenced by loadClasses().

Object cern::laser::guiplatform::util::BrowserLauncher::kSystemFolderType [static, private]

Actually an MRJOSType pointing to the System Folder on a Macintosh

Referenced by loadClasses().

Object cern::laser::guiplatform::util::BrowserLauncher::linkage [static, private]

The linkage object required for JDirect 3 on Mac OS X.

Referenced by loadClasses().

boolean cern::laser::guiplatform::util::BrowserLauncher::loadedWithoutErrors [static, private]

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.

Method cern::laser::guiplatform::util::BrowserLauncher::makeOSType [static, private]

The makeOSType method of com.apple.MacOS.OSUtils

Referenced by loadClasses(), and locateBrowser().

final int cern::laser::guiplatform::util::BrowserLauncher::MRJ_2_0 = 0 [static, private]

JVM constant for MRJ 2.0

Referenced by loadClasses(), and locateBrowser().

final int cern::laser::guiplatform::util::BrowserLauncher::MRJ_2_1 = 1 [static, private]

JVM constant for MRJ 2.1 or later

Referenced by loadClasses().

final int cern::laser::guiplatform::util::BrowserLauncher::MRJ_3_0 = 3 [static, private]

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

Referenced by loadClasses().

final int cern::laser::guiplatform::util::BrowserLauncher::MRJ_3_1 = 4 [static, private]

JVM constant for MRJ 3.1

Referenced by loadClasses().

Class cern::laser::guiplatform::util::BrowserLauncher::mrjFileUtilsClass [static, private]

The com.apple.mrj.MRJFileUtils class

Referenced by loadClasses().

Class cern::laser::guiplatform::util::BrowserLauncher::mrjOSTypeClass [static, private]

The com.apple.mrj.MRJOSType class

Referenced by loadClasses().

final String cern::laser::guiplatform::util::BrowserLauncher::NETSCAPE_OPEN_PARAMETER_END = ")'" [static, private]

final String cern::laser::guiplatform::util::BrowserLauncher::NETSCAPE_OPEN_PARAMETER_START = "'openURL(" [static, private]

final String cern::laser::guiplatform::util::BrowserLauncher::NETSCAPE_REMOTE_PARAMETER = "-remote" [static, private]

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

Method cern::laser::guiplatform::util::BrowserLauncher::openURL [static, private]

The openURL method of com.apple.mrj.MRJFileUtils

Referenced by loadClasses().

final int cern::laser::guiplatform::util::BrowserLauncher::OTHER = -1 [static, private]

JVM constant for any other platform

Method cern::laser::guiplatform::util::BrowserLauncher::putParameter [static, private]

The putParameter method of com.apple.MacOS.AppleEvent

Referenced by loadClasses().

final String cern::laser::guiplatform::util::BrowserLauncher::SECOND_WINDOWS_PARAMETER = "start" [static, private]

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

Method cern::laser::guiplatform::util::BrowserLauncher::sendNoReply [static, private]

The sendNoReply method of com.apple.MacOS.AppleEvent

Referenced by loadClasses().

final String cern::laser::guiplatform::util::BrowserLauncher::THIRD_WINDOWS_PARAMETER = "\"\"" [static, private]

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.

final int cern::laser::guiplatform::util::BrowserLauncher::WINDOWS_9x = 6 [static, private]

JVM constant for any Windows 9x JVM

final int cern::laser::guiplatform::util::BrowserLauncher::WINDOWS_NT = 5 [static, private]

JVM constant for any Windows NT JVM

The documentation for this class was generated from the following file:

BrowserLauncher.java

cern::laser::guiplatform::util::BrowserLauncher Class Reference

Static Public Member Functions

Static Package Functions

Private Member Functions

Static Private Member Functions

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation