Quick Start Guide
- Step 1: Download BrowserLauncher2.jar from SourceForge.
- Step 2: Place BrowserLauncher2.jar in your classpath.
- Step 3: Create an instance of BrowserLauncher.
BrowserLauncher launcher = new BrowserLauncher(); - Step 4: Launch a browser with a url.
launcher.openURLinBrowser("http://www.google.com");
Download Files
| File | Description |
| BrowserLauncher2.jar | A small JAR file containing only the *.class files. This is intended to be included in (distributed) client applications that use BrowserLauncher2. |
| BrowserLauncher2-all.jar | A “big” JAR file again containing the class files. Additionally, it includes the source, Javadoc API documentation, and an application for testing the library. This jar is intended to be used by developers that want to develop applications that use BrowseLauncher2. |
Test Application
BrowserLauncher2-all.jar contains an application for testing the library. To invoke the test application, enter the following on a command line: java -jar BrowserLauncher2-all.jar. The application contains a text field for entering urls (you will need to include the protocol) and a text area that records information about your environment and captures stack traces and logging information.
Image 1: Browser Launcher Test Application.
API Notes
The preferred method for using the BrowserLauncher2 api is to create an instance of BrowserLauncher (edu.stanford.ejalbert.BrowserLauncher) and invoke one of the openURLinBrowser methods:
public void openURLinBrowser(String urlString)public void openURLinBrowser(String browser, String urlString)public void openURLinBrowser(List browsers, String urlString)
The first method will invoke the user's default browser. The second and third methods are used for browser targetting which is duscussed below.
If the application will be invoking urls often, the application should wrap the BrowserLauncher instance with a singleton or use some mechanism to cache it for reuse. BrowserLauncher performs some initialization when the object is created and it would be highly inefficient to execute the initialization code every time a url is launched. There are three constructors for creating a BrowserLauncher instance:
public BrowserLauncher()public BrowserLauncher(AbstractLogger logger)public BrowserLauncher(AbstractLogger logger, BrowserLauncherErrorHandler errorHandler)
The first method uses the default logger and default error handler. The default logger ignores all logger messages. The default error handler will print a stack trace to the console if an exception is encountered. The errorHandler is used to catch and handle exceptions when executing the browser launch in a separate thread. Developers should extend AbstractLogger and BrowserLauncherErrorHandler to fit their application's needs. Take a look at the source code for the test application to see implementations of the logger and error handler interfaces.
Browser Targetting
Browser targetting provides an API for directing requests to a specific browser. This feature is fully supported on Unix/Linux and Windows but is not yet supported on Mac.
To use browser targetting, first call public List getBrowserList() to retrieve a list of available browsers. Select a name from the list of browsers and pass it with the url in the call to public void openURLinBrowser(String browser, String urlString). Developers can also pass in a List of browser names. The browsers will be tried in order until one succeeds. If a browser targetting method fails, the library will fail over to the default launching method.
Forcing a New Browser Window
Browsers react differently when an instance is running and you request a new url to be opened. Some replace the current view; some open a new tab; and some open a new window. (See Browser Behavior on the Platform Support page for details.) The BrowserLauncher2 API allows users ask for new url requests to be opened in new windows. The behavior will differ depending on the OS and the browser being targetted.
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.public void setNewWindowPolicy(boolean forceNewWindow)Sets the policy used for opening a url in a browser.
Default Browser from System Property
Another option for selecting a browser is to let the user pick the browser. The name of the preferred browser can be stored in the System properties using the key edu.stanford.ejalbert.preferred.browser. This key should be referenced using IBrowserLaunching.BROWSER_SYSTEM_PROPERTY. When launching a url using the default browser (public void openURLinBrowser(String urlString)), the browser system property will be checked. If it is set to a valid browser, the library will direct the requested url to the specified browser.
The edu.stanford.ejalbert.browserprefui package contains an action class and a dialog for offering browser choices to the user and storing the user's selection in the browser system property. This code can be called directly from your application or used as the basis for your own code. To call it directly, associate a menu item or button with the action class BrowserPrefAction.
Image 2: Preferred Browser Selection Dialog.
Browser Discovery Property (Windows only)
There are two ways to discover which browsers a user has on his system. The preferred method is to look in the registry. The secondary method is to look through the Program Files folder. Both methods have problems.
For the registry method:
- Access can be denied for security reasons.
- Applications do not consistently add entries to the registry.
We believe the access problems have been addressed. As of release 1.3, BrowserLaucher2 is using the Pure Java registry wrapper for Windows library to read the registry.
For the file path method:
- Applications must be consistent with the folder names used in the Program Files folder.
The default behavior under all versions of Windows is to first search the registry for browsers then search the Program Files folder for any browsers that are not found in the registry. If a user has problems accessing the registry, the library can be told to skip the registry search. This behavior is controlled by the system property win.browser.disc.policy defined in BrowserLauncher.WINDOWS_BROWSER_DISC_POLICY_PROPERTY. BrowserLauncher2 recognizes two values for this property: registry (BrowserLauncher.WINDOWS_BROWSER_DISC_POLICY_REGISTRY) and disk (BrowserLauncher.WINDOWS_BROWSER_DISC_POLICY_DISK).
The policy can be set at application start-up from the command line using: -Dwin.browser.disc.policy=disk. It can also be set in the code using System.setProperty(BrowserLauncher.WINDOWS_BROWSER_DISC_POLICY_PROPERTY, BrowserLauncher.WINDOWS_BROWSER_DISC_POLICY_DISK). The call to System.setProperty() must be made before the call to create a browser launcher instance: BrowserLauncher launcher = new BrowserLauncher();.
Logging
BrowserLauncher2 uses a subset of WrapLog 1.1 for logging. If you do not specify a logger instance, a default logger (NoneLogger) will be used. The default logger does not log anything.
For more information on using WrapLog, see http://sourceforge.net/projects/wraplog.
