- 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.
|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.|
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.
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(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 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.
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.
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.
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
Image 2: Preferred Browser Selection Dialog.
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:
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();.
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.