edu.stanford.ejalbert
Class BrowserLauncher

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

public class BrowserLauncher

extends Object

BrowserLauncher provides an API to open browsers (default or targetted) from within a Java application.

Primary API methods:

openURLinBrowser(browser, url) Opens the url in the requested browser.

openURLinBrowser(url) Opens the url in the default browser.

getBrowserList() Returns the list of browsers that are available for browser targetting.

The following protocols have been tested: http, mailto, and file.

This library is written completely in Java and will run on all JDK 4.x-compliant systems without modification or a need for additional libraries.

There are certain system requirements for this library, as it's running through Runtime.exec(), which is Java's way of making a native system call. Currently, Macintosh requires 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 the library authors 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 9x and NT 4.0, as well as later versions).

The browserlauncher2 project is based on the original browserlauncher project. It has been significantly altered and extended.
This is the original copyright notice and credits from the browserlauncher project:
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
End of the original copyright and credits.

Author:

Eric Albert, Markus Gebhard, Jeff Chapman

Field Summary

static String

BROWSER_SYSTEM_PROPERTY Key to system property containing name of users preferred browser.

Constructor Summary

BrowserLauncher()
Initializes the browser launcher for the operating system on which the application is running.

BrowserLauncher(AbstractLogger logger)
Initializes the browser launcher for the operating system on which the application is running.

BrowserLauncher(AbstractLogger logger, BrowserLauncherErrorHandler errorHandler)
Initializes the browser launcher for the operating system on which the application is running.

Method Summary

List	getBrowserList() Returns a list of browsers to be used for browser targetting.
AbstractLogger	getLogger() Returns the logger being used by this BrowserLauncher instance.
boolean	getNewWindowPolicy() Returns the policy used for opening a url in a browser.
static void	main(String[] args) Opens a browser and url from the command line.
static void	openURL(String urlString) Deprecated. -- create a BrowserLauncher object and use it instead of calling this static method.
void	openURLinBrowser(List browsers, String urlString) Iterates through the list of browsers until it finds one that is available on the user's system.
void	openURLinBrowser(String urlString) Attempts to open a browser and direct it to the passed url.
void	openURLinBrowser(String browser, String urlString) Attempts to open a specific browser and direct it to the passed url.
void	setNewWindowPolicy(boolean forceNewWindow) Sets the policy used for opening a url in a browser.

Methods inherited from class java.lang.Object

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

Field Detail

BROWSER_SYSTEM_PROPERTY

public static final String BROWSER_SYSTEM_PROPERTY

Key to system property containing name of users preferred browser.

The value is defined in IBrowserLaunching but exposed for general API usage from the BrowserLauncher class.

See Also:

Constant Field Values

Constructor Detail

BrowserLauncher

public BrowserLauncher()
                throws BrowserLaunchingInitializingException,
                       UnsupportedOperatingSystemException

Initializes the browser launcher for the operating system on which the application is running.

This method will use the default logger NoneLogger. All log messages are ignored by this logger.

This method will use the default errorHandler BrowserLauncherDefaultErrorHandler. It will print a stack trace to the console. The errorHandler is used to catch and handle exceptions when executing the browser launch in a separate thread.

Throws:

BrowserLaunchingInitializingException

UnsupportedOperatingSystemException

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.

This method will use the default errorHandler BrowserLauncherDefaultErrorHandler. It will print a stack trace to the console. The errorHandler is used to catch and handle exceptions when executing the browser launch in a separate thread.

Parameters:

logger - AbstractLogger

Throws:

BrowserLaunchingInitializingException

UnsupportedOperatingSystemException

BrowserLauncher

public BrowserLauncher(AbstractLogger logger,
                       BrowserLauncherErrorHandler errorHandler)
                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.

If null is passed for the errorHandler, the default errorHandler used will be BrowserLauncherDefaultErrorHandler. It will print a stack trace to the console. The errorHandler is used to catch and handle exceptions when executing the browser launch in a separate thread.

Parameters:

logger - AbstractLogger

errorHandler - BrowserLauncherErrorHandler

Throws:

BrowserLaunchingInitializingException

UnsupportedOperatingSystemException

Method Detail

openURL

public static void openURL(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(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[]

getLogger

public AbstractLogger getLogger()

Returns the logger being used by this BrowserLauncher instance.

Returns:

AbstractLogger

getBrowserList

public 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

openURLinBrowser

public void openURLinBrowser(String urlString)

Attempts to open a browser and direct it to the passed url.

Parameters:

urlString - String

openURLinBrowser

public void openURLinBrowser(String browser,
                             String urlString)

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

openURLinBrowser

public void openURLinBrowser(List browsers,
                             String urlString)

Iterates through the list of browsers until it finds one that is available on the user's system. The method then opens the browser and directs it to the passed url. This method allows the caller to try multiple browsers in a specific order.

If the list is null or empty or none of the browsers in the list are available, the code will fail over to the default browser method openURLinBrowser(url).

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

Parameters:

browsers - List

urlString - String

getNewWindowPolicy

public boolean getNewWindowPolicy()

Returns the policy used for opening a url in a browser.

If the policy is true, an attempt will be made to force the url to be opened in a new instance (window) of the browser.

If the policy is false, the url may open in a new window or a new tab.

Results will vary based on the O/S and browser being targetted.

Returns:

boolean

setNewWindowPolicy

public void setNewWindowPolicy(boolean forceNewWindow)

Sets the policy used for opening a url in a browser.

Parameters:

forceNewWindow - boolean