Class BrowserLauncher


  • class BrowserLauncher
    extends java.lang.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-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

    Version:
    1.4b1 (Released June 20, 2001)
    Author:
    Eric Albert (ejalbert@cs.stanford.edu)
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.lang.Class aeDescClass
      The com.apple.MacOS.AEDesc class
      private static java.lang.reflect.Constructor aeDescConstructor
      The (String) method of com.apple.MacOS.AEDesc
      private static java.lang.reflect.Constructor aeTargetConstructor
      The (int) method of com.apple.MacOS.AETarget
      private static java.lang.reflect.Constructor appleEventConstructor
      The (int, int, int) method of com.apple.MacOS.AppleEvent
      private static java.lang.Object browser
      The browser for the system
      private static java.lang.String errorMessage
      The message from any exception thrown throughout the initialization process.
      private static java.lang.String FINDER_CREATOR
      The creator code of the Finder on a Macintosh, which is needed to send AppleEvents to the application.
      private static java.lang.String FINDER_TYPE
      The file type of the Finder on a Macintosh.
      private static java.lang.reflect.Method findFolder
      The findFolder method of com.apple.mrj.MRJFileUtils
      private static java.lang.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 java.lang.reflect.Method getFileCreator
      The getFileCreator method of com.apple.mrj.MRJFileUtils
      private static java.lang.reflect.Method getFileType
      The getFileType method of com.apple.mrj.MRJFileUtils
      private static java.lang.String GURL_EVENT
      The name for the AppleEvent type corresponding to a GetURL event.
      private static java.lang.String JDirect_MacOSX
      The framework to reference on Mac OS X
      private static int jvm
      The Java virtual machine that we are running on.
      private static java.lang.Integer kAnyTransactionID
      The kAnyTransactionID AppleEvent code
      private static java.lang.Integer kAutoGenerateReturnID
      The kAutoGenerateReturnID AppleEvent code
      private static java.lang.Integer keyDirectObject
      The keyDirectObject AppleEvent parameter type
      private static java.lang.Object kSystemFolderType
      Actually an MRJOSType pointing to the System Folder on a Macintosh
      private static java.lang.Object linkage
      The linkage object required for JDirect 3 on Mac OS X.
      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 java.lang.reflect.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 or later
      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 MRJ 3.1
      private static java.lang.Class mrjFileUtilsClass
      The com.apple.mrj.MRJFileUtils class
      private static java.lang.Class mrjOSTypeClass
      The com.apple.mrj.MRJOSType class
      private static java.lang.String NETSCAPE_OPEN_PARAMETER_END  
      private static java.lang.String NETSCAPE_OPEN_PARAMETER_START  
      private static java.lang.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 java.lang.reflect.Method openURL
      The openURL method of com.apple.mrj.MRJFileUtils
      private static int OTHER
      JVM constant for any other platform
      private static java.lang.reflect.Method putParameter
      The putParameter method of com.apple.MacOS.AppleEvent
      private static java.lang.String SECOND_WINDOWS_PARAMETER
      The second parameter for Runtime.exec() on Windows.
      private static java.lang.reflect.Method sendNoReply
      The sendNoReply method of com.apple.MacOS.AppleEvent
      private static java.lang.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

      Constructors 
      Modifier Constructor Description
      private BrowserLauncher()
      This class should be never be instantiated; this just ensures so.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      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 java.lang.Object locateBrowser()
      Attempts to locate the default web browser on the local system.
      static void openURL​(java.lang.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 java.lang.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 java.lang.Class mrjFileUtilsClass
        The com.apple.mrj.MRJFileUtils class
      • mrjOSTypeClass

        private static java.lang.Class mrjOSTypeClass
        The com.apple.mrj.MRJOSType class
      • aeDescClass

        private static java.lang.Class aeDescClass
        The com.apple.MacOS.AEDesc class
      • aeTargetConstructor

        private static java.lang.reflect.Constructor aeTargetConstructor
        The (int) method of com.apple.MacOS.AETarget
      • appleEventConstructor

        private static java.lang.reflect.Constructor appleEventConstructor
        The (int, int, int) method of com.apple.MacOS.AppleEvent
      • aeDescConstructor

        private static java.lang.reflect.Constructor aeDescConstructor
        The (String) method of com.apple.MacOS.AEDesc
      • findFolder

        private static java.lang.reflect.Method findFolder
        The findFolder method of com.apple.mrj.MRJFileUtils
      • getFileCreator

        private static java.lang.reflect.Method getFileCreator
        The getFileCreator method of com.apple.mrj.MRJFileUtils
      • getFileType

        private static java.lang.reflect.Method getFileType
        The getFileType method of com.apple.mrj.MRJFileUtils
      • openURL

        private static java.lang.reflect.Method openURL
        The openURL method of com.apple.mrj.MRJFileUtils
      • makeOSType

        private static java.lang.reflect.Method makeOSType
        The makeOSType method of com.apple.MacOS.OSUtils
      • putParameter

        private static java.lang.reflect.Method putParameter
        The putParameter method of com.apple.MacOS.AppleEvent
      • sendNoReply

        private static java.lang.reflect.Method sendNoReply
        The sendNoReply method of com.apple.MacOS.AppleEvent
      • kSystemFolderType

        private static java.lang.Object kSystemFolderType
        Actually an MRJOSType pointing to the System Folder on a Macintosh
      • keyDirectObject

        private static java.lang.Integer keyDirectObject
        The keyDirectObject AppleEvent parameter type
      • kAutoGenerateReturnID

        private static java.lang.Integer kAutoGenerateReturnID
        The kAutoGenerateReturnID AppleEvent code
      • kAnyTransactionID

        private static java.lang.Integer kAnyTransactionID
        The kAnyTransactionID AppleEvent code
      • linkage

        private static java.lang.Object linkage
        The linkage object required for JDirect 3 on Mac OS X.
      • JDirect_MacOSX

        private static final java.lang.String JDirect_MacOSX
        The framework to reference on Mac OS X
        See Also:
        Constant Field Values
      • MRJ_2_1

        private static final int MRJ_2_1
        JVM constant for MRJ 2.1 or later
        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
      • 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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.String SECOND_WINDOWS_PARAMETER
        The second parameter for Runtime.exec() on Windows.
        See Also:
        Constant Field Values
      • THIRD_WINDOWS_PARAMETER

        private static final java.lang.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 java.lang.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 java.lang.String NETSCAPE_OPEN_PARAMETER_START
        See Also:
        Constant Field Values
      • NETSCAPE_OPEN_PARAMETER_END

        private static final java.lang.String NETSCAPE_OPEN_PARAMETER_END
        See Also:
        Constant Field Values
      • errorMessage

        private static java.lang.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

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

        private static java.lang.Object locateBrowser()
        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.
      • openURL

        public static void openURL​(java.lang.String url)
                            throws java.io.IOException
        Attempts to open the default web browser to the given URL.
        Parameters:
        url - The URL to open
        Throws:
        java.io.IOException - If the web browser could not be located or does not run
      • ICStart

        private static int ICStart​(int[] instance,
                                   int signature)
        Methods required for Mac OS X. The presence of native methods does not cause any problems on other platforms.
      • ICStop

        private static int ICStop​(int[] instance)
      • ICLaunchURL

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