2 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3 * Copyright (C) $$Year-Rel$$ The Jalview Authors
5 * This file is part of Jalview.
7 * Jalview is free software: you can redistribute it and/or
8 * modify it under the terms of the GNU General Public License
9 * as published by the Free Software Foundation, either version 3
10 * of the License, or (at your option) any later version.
12 * Jalview is distributed in the hope that it will be useful, but
13 * WITHOUT ANY WARRANTY; without even the implied warranty
14 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
15 * PURPOSE. See the GNU General Public License for more details.
17 * You should have received a copy of the GNU General Public License
18 * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
19 * The Jalview Authors are detailed in the 'AUTHORS' file.
23 import jalview.bin.Cache;
26 import java.io.IOException;
27 import java.lang.reflect.Constructor;
28 import java.lang.reflect.Field;
29 import java.lang.reflect.InvocationTargetException;
30 import java.lang.reflect.Method;
33 * BrowserLauncher is a class that provides one static method, openURL, which
34 * opens the default web browser for the current user of the system to the given
35 * URL. It may support other protocols depending on the system -- mailto, ftp,
36 * etc. -- but that has not been rigorously tested and is not guaranteed to
39 * Yes, this is platform-specific code, and yes, it may rely on classes on
40 * certain platforms that are not part of the standard JDK. What we're trying to
41 * do, though, is to take something that's frequently desirable but inherently
42 * platform-specific -- opening a default browser -- and allow programmers (you,
43 * for example) to do so without worrying about dropping into native code or
44 * doing anything else similarly evil.
46 * Anyway, this code is completely in Java and will run on all JDK 1.1-compliant
47 * systems without modification or a need for additional libraries. All classes
48 * that are required on certain platforms to allow this to run are dynamically
49 * loaded at runtime via reflection and, if not found, will not cause this to do
50 * anything other than returning an error when opening the browser.
52 * There are certain system requirements for this class, as it's running through
53 * Runtime.exec(), which is Java's way of making a native system call.
54 * Currently, this requires that a Macintosh have a Finder which supports the
55 * GURL event, which is true for Mac OS 8.0 and 8.1 systems that have the
56 * Internet Scripting AppleScript dictionary installed in the Scripting
57 * Additions folder in the Extensions folder (which is installed by default as
58 * far as I know under Mac OS 8.0 and 8.1), and for all Mac OS 8.5 and later
59 * systems. On Windows, it only runs under Win32 systems (Windows 95, 98, and NT
60 * 4.0, as well as later versions of all). On other systems, this drops back
61 * from the inherently platform-sensitive concept of a default browser and
62 * simply attempts to launch Netscape via a shell command.
64 * This code is Copyright 1999-2001 by Eric Albert (ejalbert\@cs.stanford.edu)
65 * and may be redistributed or modified in any form without restrictions as long
66 * as the portion of this comment from this paragraph through the end of the
67 * comment is not removed. The author requests that he be notified of any
68 * application, applet, or other binary that makes use of this code, but that's
69 * more out of curiosity than anything and is not required. This software
70 * includes no warranty. The author is not repsonsible for any loss of data or
71 * functionality or any adverse or unexpected effects of using this software.
74 * Steven Spencer, JavaWorld magazine
75 * (<a href="http://www.javaworld.com/javaworld/javatips/jw-javatip66.html">Java
77 * Thanks also to Ron B. Yeh, Eric Shapiro, Ben Engber, Paul Teitlebaum, Andrea
78 * Cantatore, Larry Barowski, Trevor Bedzek, Frank Miedrich, and Ron Rabakukk
80 * @author Eric Albert (<a href=
81 * "mailto:ejalbert@cs.stanford.edu">ejalbert@cs.stanford.edu</a>)
82 * @version 1.4b1 (Released June 20, 2001)
84 public class BrowserLauncher
87 * The Java virtual machine that we are running on. Actually, in most cases we
88 * only care about the operating system, but some operating systems require us
89 * to switch on the VM.
91 private static int jvm;
93 /** The browser for the system */
94 private static Object browser;
97 * Caches whether any classes, methods, and fields that are not part of the
98 * JDK and need to be dynamically loaded at runtime loaded successfully.
100 * Note that if this is <code>false</code>, <code>openURL()</code> will always
101 * return an IOException.
103 private static boolean loadedWithoutErrors;
105 /** The com.apple.mrj.MRJFileUtils class */
106 private static Class mrjFileUtilsClass;
108 /** The com.apple.mrj.MRJOSType class */
109 private static Class mrjOSTypeClass;
111 /** The com.apple.MacOS.AEDesc class */
112 private static Class aeDescClass;
114 /** The <init>(int) method of com.apple.MacOS.AETarget */
115 private static Constructor aeTargetConstructor;
117 /** The <init>(int, int, int) method of com.apple.MacOS.AppleEvent */
118 private static Constructor appleEventConstructor;
120 /** The <init>(String) method of com.apple.MacOS.AEDesc */
121 private static Constructor aeDescConstructor;
123 /** The findFolder method of com.apple.mrj.MRJFileUtils */
124 private static Method findFolder;
126 /** The getFileCreator method of com.apple.mrj.MRJFileUtils */
127 private static Method getFileCreator;
129 /** The getFileType method of com.apple.mrj.MRJFileUtils */
130 private static Method getFileType;
132 /** The openURL method of com.apple.mrj.MRJFileUtils */
133 private static Method openURL;
135 /** The makeOSType method of com.apple.MacOS.OSUtils */
136 private static Method makeOSType;
138 /** The putParameter method of com.apple.MacOS.AppleEvent */
139 private static Method putParameter;
141 /** The sendNoReply method of com.apple.MacOS.AppleEvent */
142 private static Method sendNoReply;
144 /** Actually an MRJOSType pointing to the System Folder on a Macintosh */
145 private static Object kSystemFolderType;
147 /** The keyDirectObject AppleEvent parameter type */
148 private static Integer keyDirectObject;
150 /** The kAutoGenerateReturnID AppleEvent code */
151 private static Integer kAutoGenerateReturnID;
153 /** The kAnyTransactionID AppleEvent code */
154 private static Integer kAnyTransactionID;
156 /** The linkage object required for JDirect 3 on Mac OS X. */
157 private static Object linkage;
159 /** The framework to reference on Mac OS X */
160 private static final String JDirect_MacOSX = "/System/Library/Frameworks/Carbon.framework/Frameworks/HIToolbox.framework/HIToolbox";
162 /** JVM constant for MRJ 2.0 */
163 private static final int MRJ_2_0 = 0;
165 /** JVM constant for MRJ 2.1 or later */
166 private static final int MRJ_2_1 = 1;
168 /** JVM constant for Java on Mac OS X 10.0 (MRJ 3.0) */
169 private static final int MRJ_3_0 = 3;
171 /** JVM constant for MRJ 3.1 */
172 private static final int MRJ_3_1 = 4;
174 /** JVM constant for any Windows NT JVM */
175 private static final int WINDOWS_NT = 5;
177 /** JVM constant for any Windows 9x JVM */
178 private static final int WINDOWS_9x = 6;
180 /** JVM constant for any other platform */
181 private static final int OTHER = -1;
184 * The file type of the Finder on a Macintosh. Hardcoding "Finder" would keep
185 * non-U.S. English systems from working properly.
187 private static final String FINDER_TYPE = "FNDR";
190 * The creator code of the Finder on a Macintosh, which is needed to send
191 * AppleEvents to the application.
193 private static final String FINDER_CREATOR = "MACS";
195 /** The name for the AppleEvent type corresponding to a GetURL event. */
196 private static final String GURL_EVENT = "GURL";
199 * The first parameter that needs to be passed into Runtime.exec() to open the
200 * default web browser on Windows.
202 private static final String FIRST_WINDOWS_PARAMETER = "/c";
204 /** The second parameter for Runtime.exec() on Windows. */
205 private static final String SECOND_WINDOWS_PARAMETER = "start";
208 * The third parameter for Runtime.exec() on Windows. This is a "title"
209 * parameter that the command line expects. Setting this parameter allows URLs
210 * containing spaces to work.
212 private static final String THIRD_WINDOWS_PARAMETER = "\"\"";
215 * The shell parameters for Netscape that opens a given URL in an already-open
216 * copy of Netscape on many command-line systems.
218 private static final String NETSCAPE_REMOTE_PARAMETER = "-remote";
220 private static final String NETSCAPE_OPEN_PARAMETER_START = "openURL(";
222 private static final String NETSCAPE_OPEN_NEW_WINDOW = ", new-window";
224 private static final String NETSCAPE_OPEN_PARAMETER_END = ")";
227 * The message from any exception thrown throughout the initialization
230 private static String errorMessage;
233 * An initialization block that determines the operating system and loads the
234 * necessary runtime data.
239 loadedWithoutErrors = true;
241 if (!Platform.isJS())
249 String osName = System.getProperty("os.name");
251 if (osName.startsWith("Mac OS"))
253 String mrjVersion = System.getProperty("mrj.version");
254 String majorMRJVersion;
255 if (mrjVersion == null)
257 // must be on some later build with mrj support
258 majorMRJVersion = "3.1";
262 majorMRJVersion = mrjVersion.substring(0, 3);
267 double version = Double.valueOf(majorMRJVersion).doubleValue();
273 else if ((version >= 2.1) && (version < 3))
275 // Assume that all 2.x versions of MRJ work the same. MRJ 2.1 actually
276 // works via Runtime.exec() and 2.2 supports that but has an openURL()
278 // as well that we currently ignore.
281 else if (version == 3.0)
285 else if (version >= 3.1)
287 // Assume that all 3.1 and later versions of MRJ work the same.
292 loadedWithoutErrors = false;
293 errorMessage = "Unsupported MRJ version: " + version;
295 } catch (NumberFormatException nfe)
297 loadedWithoutErrors = false;
298 errorMessage = "Invalid MRJ version: " + mrjVersion;
301 else if (osName.startsWith("Windows"))
303 if (osName.indexOf("9") != -1)
317 if (loadedWithoutErrors)
318 { // if we haven't hit any errors yet
319 loadedWithoutErrors = loadClasses();
325 * This class should be never be instantiated; this just ensures so.
327 private BrowserLauncher()
332 * Called by a static initializer to load any classes, fields, and methods
333 * required at runtime to locate the user's web browser.
335 * @return <code>true</code> if all intialization succeeded <code>false</code>
336 * if any portion of the initialization failed
338 private static boolean loadClasses()
341 if (!Platform.isJS())
355 Class aeTargetClass = Class.forName("com.apple.MacOS.AETarget");
356 Class osUtilsClass = Class.forName("com.apple.MacOS.OSUtils");
357 Class appleEventClass = Class.forName("com.apple.MacOS.AppleEvent");
358 Class aeClass = Class.forName("com.apple.MacOS.ae");
359 aeDescClass = Class.forName("com.apple.MacOS.AEDesc");
361 aeTargetConstructor = aeTargetClass
362 .getDeclaredConstructor(new Class[]
364 appleEventConstructor = appleEventClass
365 .getDeclaredConstructor(new Class[]
366 { int.class, int.class, aeTargetClass, int.class,
368 aeDescConstructor = aeDescClass
369 .getDeclaredConstructor(new Class[]
372 makeOSType = osUtilsClass.getDeclaredMethod("makeOSType",
375 putParameter = appleEventClass.getDeclaredMethod("putParameter",
377 { int.class, aeDescClass });
378 sendNoReply = appleEventClass.getDeclaredMethod("sendNoReply",
381 Field keyDirectObjectField = aeClass
382 .getDeclaredField("keyDirectObject");
383 keyDirectObject = (Integer) keyDirectObjectField.get(null);
385 Field autoGenerateReturnIDField = appleEventClass
386 .getDeclaredField("kAutoGenerateReturnID");
387 kAutoGenerateReturnID = (Integer) autoGenerateReturnIDField
390 Field anyTransactionIDField = appleEventClass
391 .getDeclaredField("kAnyTransactionID");
392 kAnyTransactionID = (Integer) anyTransactionIDField.get(null);
393 } catch (ClassNotFoundException cnfe)
395 errorMessage = cnfe.getMessage();
398 } catch (NoSuchMethodException nsme)
400 errorMessage = nsme.getMessage();
403 } catch (NoSuchFieldException nsfe)
405 errorMessage = nsfe.getMessage();
408 } catch (IllegalAccessException iae)
410 errorMessage = iae.getMessage();
421 mrjFileUtilsClass = Class.forName("com.apple.mrj.MRJFileUtils");
422 mrjOSTypeClass = Class.forName("com.apple.mrj.MRJOSType");
424 Field systemFolderField = mrjFileUtilsClass
425 .getDeclaredField("kSystemFolderType");
426 kSystemFolderType = systemFolderField.get(null);
427 findFolder = mrjFileUtilsClass.getDeclaredMethod("findFolder",
430 getFileCreator = mrjFileUtilsClass
431 .getDeclaredMethod("getFileCreator", new Class[]
433 getFileType = mrjFileUtilsClass.getDeclaredMethod("getFileType",
436 } catch (ClassNotFoundException cnfe)
438 errorMessage = cnfe.getMessage();
441 } catch (NoSuchFieldException nsfe)
443 errorMessage = nsfe.getMessage();
446 } catch (NoSuchMethodException nsme)
448 errorMessage = nsme.getMessage();
451 } catch (SecurityException se)
453 errorMessage = se.getMessage();
456 } catch (IllegalAccessException iae)
458 errorMessage = iae.getMessage();
469 Class linker = Class.forName("com.apple.mrj.jdirect.Linker");
470 Constructor constructor = linker
471 .getConstructor(new Class[]
473 linkage = constructor
474 .newInstance(new Object[]
475 { BrowserLauncher.class });
476 } catch (ClassNotFoundException cnfe)
478 errorMessage = cnfe.getMessage();
481 } catch (NoSuchMethodException nsme)
483 errorMessage = nsme.getMessage();
486 } catch (InvocationTargetException ite)
488 errorMessage = ite.getMessage();
491 } catch (InstantiationException ie)
493 errorMessage = ie.getMessage();
496 } catch (IllegalAccessException iae)
498 errorMessage = iae.getMessage();
509 mrjFileUtilsClass = Class.forName("com.apple.mrj.MRJFileUtils");
510 openURL = mrjFileUtilsClass.getDeclaredMethod("openURL",
513 } catch (ClassNotFoundException cnfe)
515 errorMessage = cnfe.getMessage();
518 } catch (NoSuchMethodException nsme)
520 errorMessage = nsme.getMessage();
536 * Attempts to locate the default web browser on the local system. s results
537 * so it only locates the browser once for each use of this class per JVM
540 * @return The browser for the system. Note that this may not be what you
541 * would consider to be a standard web browser; instead, it's the
542 * application that gets called to open the default web browser. In
543 * some cases, this will be a non-String object that provides the
544 * means of calling the default browser.
546 private static Object locateBrowser()
548 if (!Platform.isJS())
567 Integer finderCreatorCode = (Integer) makeOSType.invoke(null,
570 Object aeTarget = aeTargetConstructor
571 .newInstance(new Object[]
572 { finderCreatorCode });
573 Integer gurlType = (Integer) makeOSType.invoke(null,
576 Object appleEvent = appleEventConstructor
577 .newInstance(new Object[]
578 { gurlType, gurlType, aeTarget, kAutoGenerateReturnID,
579 kAnyTransactionID });
581 // Don't set browser = appleEvent because then the next time we call
582 // locateBrowser(), we'll get the same AppleEvent, to which we'll
584 // added the relevant parameter. Instead, regenerate the AppleEvent
586 // There's probably a way to do this better; if any has any ideas,
590 } catch (IllegalAccessException iae)
593 errorMessage = iae.getMessage();
596 } catch (InstantiationException ie)
599 errorMessage = ie.getMessage();
602 } catch (InvocationTargetException ite)
605 errorMessage = ite.getMessage();
616 systemFolder = (File) findFolder.invoke(null,
618 { kSystemFolderType });
619 } catch (IllegalArgumentException iare)
622 errorMessage = iare.getMessage();
625 } catch (IllegalAccessException iae)
628 errorMessage = iae.getMessage();
631 } catch (InvocationTargetException ite)
634 errorMessage = ite.getTargetException().getClass() + ": "
635 + ite.getTargetException().getMessage();
640 String[] systemFolderFiles = systemFolder.list();
642 // Avoid a FilenameFilter because that can't be stopped mid-list
643 for (int i = 0; i < systemFolderFiles.length; i++)
647 File file = new File(systemFolder, systemFolderFiles[i]);
654 // We're looking for a file with a creator code of 'MACS' and
655 // a type of 'FNDR'. Only requiring the type results in non-Finder
656 // applications being picked up on certain Mac OS 9 systems,
657 // especially German ones, and sending a GURL event to those
658 // applications results in a logout under Multiple Users.
659 Object fileType = getFileType.invoke(null, new Object[] { file });
661 if (FINDER_TYPE.equals(fileType.toString()))
663 Object fileCreator = getFileCreator.invoke(null,
667 if (FINDER_CREATOR.equals(fileCreator.toString()))
669 browser = file.toString(); // Actually the Finder, but that's OK
674 } catch (IllegalArgumentException iare)
676 errorMessage = iare.getMessage();
679 } catch (IllegalAccessException iae)
682 errorMessage = iae.getMessage();
685 } catch (InvocationTargetException ite)
688 errorMessage = ite.getTargetException().getClass() + ": "
689 + ite.getTargetException().getMessage();
701 browser = ""; // Return something non-null
711 browser = "command.com";
717 browser = Cache.getDefault("DEFAULT_BROWSER", "firefox");
729 * used to ensure that browser is up-to-date after a configuration change
730 * (Unix DEFAULT_BROWSER property change).
732 public static void resetBrowser()
738 * Attempts to open the default web browser to the given URL.
742 * @throws IOException
743 * If the web browser could not be located or does not run
745 public static void openURL(String url) throws IOException
750 Platform.openURL(url);
761 if (!loadedWithoutErrors)
763 throw new IOException(MessageManager
764 .formatMessage("exception.browser_not_found", new String[]
768 Object browser = locateBrowser();
772 throw new IOException(MessageManager.formatMessage(
773 "exception.browser_unable_to_locate", new String[]
781 Object aeDesc = null;
785 aeDesc = aeDescConstructor.newInstance(new Object[] { url });
786 putParameter.invoke(browser,
788 { keyDirectObject, aeDesc });
789 sendNoReply.invoke(browser, new Object[] {});
790 } catch (InvocationTargetException ite)
792 throw new IOException(MessageManager.formatMessage(
793 "exception.invocation_target_exception_creating_aedesc",
795 { ite.getMessage() }));
796 } catch (IllegalAccessException iae)
798 throw new IOException(MessageManager.formatMessage(
799 "exception.illegal_access_building_apple_evt", new String[]
800 { iae.getMessage() }));
801 } catch (InstantiationException ie)
803 throw new IOException(MessageManager.formatMessage(
804 "exception.illegal_access_building_apple_evt", new String[]
805 { ie.getMessage() }));
808 aeDesc = null; // Encourage it to get disposed if it was created
809 browser = null; // Ditto
815 Runtime.getRuntime().exec(new String[] { (String) browser, url });
821 int[] instance = new int[1];
822 int result = ICStart(instance, 0);
826 int[] selectionStart = new int[] { 0 };
827 byte[] urlBytes = url.getBytes();
828 int[] selectionEnd = new int[] { urlBytes.length };
829 result = ICLaunchURL(instance[0], new byte[] { 0 }, urlBytes,
830 urlBytes.length, selectionStart, selectionEnd);
834 // Ignore the return value; the URL was launched successfully
835 // regardless of what happens here.
840 throw new IOException(MessageManager.formatMessage(
841 "exception.unable_to_launch_url", new String[]
842 { Integer.valueOf(result).toString() }));
847 throw new IOException(MessageManager.formatMessage(
848 "exception.unable_to_create_internet_config", new String[]
849 { Integer.valueOf(result).toString() }));
858 openURL.invoke(null, new Object[] { url });
859 } catch (InvocationTargetException ite)
861 throw new IOException(MessageManager.formatMessage(
862 "exception.invocation_target_calling_url", new String[]
863 { ite.getMessage() }));
864 } catch (IllegalAccessException iae)
866 throw new IOException(MessageManager.formatMessage(
867 "exception.illegal_access_calling_url", new String[]
868 { iae.getMessage() }));
876 // Add quotes around the URL to allow ampersands and other special
877 // characters to work.
878 Process process = Runtime.getRuntime()
880 { (String) browser, FIRST_WINDOWS_PARAMETER,
881 SECOND_WINDOWS_PARAMETER, THIRD_WINDOWS_PARAMETER,
884 // This avoids a memory leak on some versions of Java on Windows.
885 // That's hinted at in
886 // <http://developer.java.sun.com/developer/qow/archive/68/>.
891 } catch (InterruptedException ie)
893 throw new IOException(MessageManager.formatMessage(
894 "exception.interrupted_launching_browser", new String[]
895 { ie.getMessage() }));
902 // Assume that we're on Unix and that Netscape (actually Firefox) is
904 // First, attempt to open the URL in a currently running session of
909 * System.out.println("Executing : "+browser+" "+
910 * NETSCAPE_REMOTE_PARAMETER+" "+ NETSCAPE_OPEN_PARAMETER_START + url +
911 * NETSCAPE_OPEN_NEW_WINDOW + NETSCAPE_OPEN_PARAMETER_END);
913 process = Runtime.getRuntime()
915 { (String) browser, NETSCAPE_REMOTE_PARAMETER,
917 NETSCAPE_OPEN_PARAMETER_START + url
918 + NETSCAPE_OPEN_NEW_WINDOW
919 + NETSCAPE_OPEN_PARAMETER_END });
923 int exitCode = process.waitFor();
926 { // if Netscape was not open
927 Runtime.getRuntime().exec(new String[] { (String) browser, url });
929 } catch (InterruptedException ie)
931 throw new IOException(MessageManager.formatMessage(
932 "exception.interrupted_launching_browser", new String[]
933 { ie.getMessage() }));
940 // This should never occur, but if it does, we'll try the simplest thing
942 Runtime.getRuntime().exec(new String[] { (String) browser, url });
951 * Methods required for Mac OS X. The presence of native methods does not
952 * cause any problems on other platforms.
954 private native static int ICStart(int[] instance, int signature);
956 private native static int ICStop(int[] instance);
958 private native static int ICLaunchURL(int instance, byte[] hint,
959 byte[] data, int len, int[] selectionStart, int[] selectionEnd);