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 (<a
75 * href="http://www.javaworld.com/javaworld/javatips/jw-javatip66.html">Java Tip
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
81 * href="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.
238 loadedWithoutErrors = true;
240 String osName = System.getProperty("os.name");
242 if (osName.startsWith("Mac OS"))
244 String mrjVersion = System.getProperty("mrj.version");
245 String majorMRJVersion;
246 if (mrjVersion == null)
248 // must be on some later build with mrj support
249 majorMRJVersion = "3.1";
253 majorMRJVersion = mrjVersion.substring(0, 3);
258 double version = Double.valueOf(majorMRJVersion).doubleValue();
264 else if ((version >= 2.1) && (version < 3))
266 // Assume that all 2.x versions of MRJ work the same. MRJ 2.1 actually
267 // works via Runtime.exec() and 2.2 supports that but has an openURL()
269 // as well that we currently ignore.
272 else if (version == 3.0)
276 else if (version >= 3.1)
278 // Assume that all 3.1 and later versions of MRJ work the same.
283 loadedWithoutErrors = false;
284 errorMessage = "Unsupported MRJ version: " + version;
286 } catch (NumberFormatException nfe)
288 loadedWithoutErrors = false;
289 errorMessage = "Invalid MRJ version: " + mrjVersion;
292 else if (osName.startsWith("Windows"))
294 if (osName.indexOf("9") != -1)
308 if (loadedWithoutErrors)
309 { // if we haven't hit any errors yet
310 loadedWithoutErrors = loadClasses();
315 * This class should be never be instantiated; this just ensures so.
317 private BrowserLauncher()
322 * Called by a static initializer to load any classes, fields, and methods
323 * required at runtime to locate the user's web browser.
325 * @return <code>true</code> if all intialization succeeded <code>false</code>
326 * if any portion of the initialization failed
328 private static boolean loadClasses()
336 Class aeTargetClass = Class.forName("com.apple.MacOS.AETarget");
337 Class osUtilsClass = Class.forName("com.apple.MacOS.OSUtils");
338 Class appleEventClass = Class.forName("com.apple.MacOS.AppleEvent");
339 Class aeClass = Class.forName("com.apple.MacOS.ae");
340 aeDescClass = Class.forName("com.apple.MacOS.AEDesc");
342 aeTargetConstructor = aeTargetClass
343 .getDeclaredConstructor(new Class[]
345 appleEventConstructor = appleEventClass
346 .getDeclaredConstructor(new Class[]
347 { int.class, int.class, aeTargetClass, int.class, int.class });
348 aeDescConstructor = aeDescClass.getDeclaredConstructor(new Class[]
351 makeOSType = osUtilsClass.getDeclaredMethod("makeOSType",
354 putParameter = appleEventClass.getDeclaredMethod("putParameter",
356 { int.class, aeDescClass });
357 sendNoReply = appleEventClass.getDeclaredMethod("sendNoReply",
361 Field keyDirectObjectField = aeClass
362 .getDeclaredField("keyDirectObject");
363 keyDirectObject = (Integer) keyDirectObjectField.get(null);
365 Field autoGenerateReturnIDField = appleEventClass
366 .getDeclaredField("kAutoGenerateReturnID");
367 kAutoGenerateReturnID = (Integer) autoGenerateReturnIDField
370 Field anyTransactionIDField = appleEventClass
371 .getDeclaredField("kAnyTransactionID");
372 kAnyTransactionID = (Integer) anyTransactionIDField.get(null);
373 } catch (ClassNotFoundException cnfe)
375 errorMessage = cnfe.getMessage();
378 } catch (NoSuchMethodException nsme)
380 errorMessage = nsme.getMessage();
383 } catch (NoSuchFieldException nsfe)
385 errorMessage = nsfe.getMessage();
388 } catch (IllegalAccessException iae)
390 errorMessage = iae.getMessage();
401 mrjFileUtilsClass = Class.forName("com.apple.mrj.MRJFileUtils");
402 mrjOSTypeClass = Class.forName("com.apple.mrj.MRJOSType");
404 Field systemFolderField = mrjFileUtilsClass
405 .getDeclaredField("kSystemFolderType");
406 kSystemFolderType = systemFolderField.get(null);
407 findFolder = mrjFileUtilsClass.getDeclaredMethod("findFolder",
410 getFileCreator = mrjFileUtilsClass.getDeclaredMethod(
411 "getFileCreator", new Class[]
413 getFileType = mrjFileUtilsClass.getDeclaredMethod("getFileType",
416 } catch (ClassNotFoundException cnfe)
418 errorMessage = cnfe.getMessage();
421 } catch (NoSuchFieldException nsfe)
423 errorMessage = nsfe.getMessage();
426 } catch (NoSuchMethodException nsme)
428 errorMessage = nsme.getMessage();
431 } catch (SecurityException se)
433 errorMessage = se.getMessage();
436 } catch (IllegalAccessException iae)
438 errorMessage = iae.getMessage();
449 Class linker = Class.forName("com.apple.mrj.jdirect.Linker");
450 Constructor constructor = linker.getConstructor(new Class[]
452 linkage = constructor.newInstance(new Object[]
453 { BrowserLauncher.class });
454 } catch (ClassNotFoundException cnfe)
456 errorMessage = cnfe.getMessage();
459 } catch (NoSuchMethodException nsme)
461 errorMessage = nsme.getMessage();
464 } catch (InvocationTargetException ite)
466 errorMessage = ite.getMessage();
469 } catch (InstantiationException ie)
471 errorMessage = ie.getMessage();
474 } catch (IllegalAccessException iae)
476 errorMessage = iae.getMessage();
487 mrjFileUtilsClass = Class.forName("com.apple.mrj.MRJFileUtils");
488 openURL = mrjFileUtilsClass.getDeclaredMethod("openURL",
491 } catch (ClassNotFoundException cnfe)
493 errorMessage = cnfe.getMessage();
496 } catch (NoSuchMethodException nsme)
498 errorMessage = nsme.getMessage();
513 * Attempts to locate the default web browser on the local system. s results
514 * so it only locates the browser once for each use of this class per JVM
517 * @return The browser for the system. Note that this may not be what you
518 * would consider to be a standard web browser; instead, it's the
519 * application that gets called to open the default web browser. In
520 * some cases, this will be a non-String object that provides the
521 * means of calling the default browser.
523 private static Object locateBrowser()
536 Integer finderCreatorCode = (Integer) makeOSType.invoke(null,
539 Object aeTarget = aeTargetConstructor.newInstance(new Object[]
540 { finderCreatorCode });
541 Integer gurlType = (Integer) makeOSType.invoke(null, new Object[]
543 Object appleEvent = appleEventConstructor.newInstance(new Object[]
544 { gurlType, gurlType, aeTarget, kAutoGenerateReturnID,
545 kAnyTransactionID });
547 // Don't set browser = appleEvent because then the next time we call
548 // locateBrowser(), we'll get the same AppleEvent, to which we'll
550 // added the relevant parameter. Instead, regenerate the AppleEvent
552 // There's probably a way to do this better; if any has any ideas,
556 } catch (IllegalAccessException iae)
559 errorMessage = iae.getMessage();
562 } catch (InstantiationException ie)
565 errorMessage = ie.getMessage();
568 } catch (InvocationTargetException ite)
571 errorMessage = ite.getMessage();
582 systemFolder = (File) findFolder.invoke(null, new Object[]
583 { kSystemFolderType });
584 } catch (IllegalArgumentException iare)
587 errorMessage = iare.getMessage();
590 } catch (IllegalAccessException iae)
593 errorMessage = iae.getMessage();
596 } catch (InvocationTargetException ite)
599 errorMessage = ite.getTargetException().getClass() + ": "
600 + ite.getTargetException().getMessage();
605 String[] systemFolderFiles = systemFolder.list();
607 // Avoid a FilenameFilter because that can't be stopped mid-list
608 for (int i = 0; i < systemFolderFiles.length; i++)
612 File file = new File(systemFolder, systemFolderFiles[i]);
619 // We're looking for a file with a creator code of 'MACS' and
620 // a type of 'FNDR'. Only requiring the type results in non-Finder
621 // applications being picked up on certain Mac OS 9 systems,
622 // especially German ones, and sending a GURL event to those
623 // applications results in a logout under Multiple Users.
624 Object fileType = getFileType.invoke(null, new Object[]
627 if (FINDER_TYPE.equals(fileType.toString()))
629 Object fileCreator = getFileCreator.invoke(null, new Object[]
632 if (FINDER_CREATOR.equals(fileCreator.toString()))
634 browser = file.toString(); // Actually the Finder, but that's OK
639 } catch (IllegalArgumentException iare)
641 errorMessage = iare.getMessage();
644 } catch (IllegalAccessException iae)
647 errorMessage = iae.getMessage();
650 } catch (InvocationTargetException ite)
653 errorMessage = ite.getTargetException().getClass() + ": "
654 + ite.getTargetException().getMessage();
666 browser = ""; // Return something non-null
676 browser = "command.com";
682 browser = Cache.getDefault("DEFAULT_BROWSER", "firefox");
691 * used to ensure that browser is up-to-date after a configuration change
692 * (Unix DEFAULT_BROWSER property change).
694 public static void resetBrowser()
700 * Attempts to open the default web browser to the given URL.
704 * @throws IOException
705 * If the web browser could not be located or does not run
707 public static void openURL(String url) throws IOException
709 if (!loadedWithoutErrors)
711 throw new IOException(MessageManager.formatMessage("exception.browser_not_found", new String[]{errorMessage}));
714 Object browser = locateBrowser();
718 throw new IOException(MessageManager.formatMessage("exception.browser_unable_to_locate", new String[]{errorMessage}));
725 Object aeDesc = null;
729 aeDesc = aeDescConstructor.newInstance(new Object[]
731 putParameter.invoke(browser, new Object[]
732 { keyDirectObject, aeDesc });
733 sendNoReply.invoke(browser, new Object[]
735 } catch (InvocationTargetException ite)
737 throw new IOException(MessageManager.formatMessage("exception.invocation_target_exception_creating_aedesc", new String[]{ite.getMessage()}));
738 } catch (IllegalAccessException iae)
740 throw new IOException(MessageManager.formatMessage("exception.illegal_access_building_apple_evt", new String[]{iae.getMessage()}));
741 } catch (InstantiationException ie)
743 throw new IOException(MessageManager.formatMessage("exception.illegal_access_building_apple_evt", new String[]{ie.getMessage()}));
746 aeDesc = null; // Encourage it to get disposed if it was created
747 browser = null; // Ditto
753 Runtime.getRuntime().exec(new String[]
754 { (String) browser, url });
760 int[] instance = new int[1];
761 int result = ICStart(instance, 0);
765 int[] selectionStart = new int[]
767 byte[] urlBytes = url.getBytes();
768 int[] selectionEnd = new int[]
770 result = ICLaunchURL(instance[0], new byte[]
771 { 0 }, urlBytes, urlBytes.length, selectionStart, selectionEnd);
775 // Ignore the return value; the URL was launched successfully
776 // regardless of what happens here.
781 throw new IOException(MessageManager.formatMessage("exception.unable_to_launch_url", new String[]{Integer.valueOf(result).toString()}));
786 throw new IOException(MessageManager.formatMessage("exception.unable_to_create_internet_config", new String[]{Integer.valueOf(result).toString()}));
795 openURL.invoke(null, new Object[]
797 } catch (InvocationTargetException ite)
799 throw new IOException(MessageManager.formatMessage("exception.invocation_target_calling_url", new String[]{ite.getMessage()}));
800 } catch (IllegalAccessException iae)
802 throw new IOException(MessageManager.formatMessage("exception.illegal_access_calling_url", new String[]{iae.getMessage()}));
810 // Add quotes around the URL to allow ampersands and other special
811 // characters to work.
812 Process process = Runtime.getRuntime().exec(
814 { (String) browser, FIRST_WINDOWS_PARAMETER,
815 SECOND_WINDOWS_PARAMETER, THIRD_WINDOWS_PARAMETER,
818 // This avoids a memory leak on some versions of Java on Windows.
819 // That's hinted at in
820 // <http://developer.java.sun.com/developer/qow/archive/68/>.
825 } catch (InterruptedException ie)
827 throw new IOException(MessageManager.formatMessage("exception.interrupted_launching_browser", new String[]{ie.getMessage()}));
834 // Assume that we're on Unix and that Netscape (actually Firefox) is
836 // First, attempt to open the URL in a currently running session of
841 * System.out.println("Executing : "+browser+" "+
842 * NETSCAPE_REMOTE_PARAMETER+" "+ NETSCAPE_OPEN_PARAMETER_START + url +
843 * NETSCAPE_OPEN_NEW_WINDOW + NETSCAPE_OPEN_PARAMETER_END);
845 process = Runtime.getRuntime().exec(
849 NETSCAPE_REMOTE_PARAMETER,
851 NETSCAPE_OPEN_PARAMETER_START + url
852 + NETSCAPE_OPEN_NEW_WINDOW
853 + NETSCAPE_OPEN_PARAMETER_END });
857 int exitCode = process.waitFor();
860 { // if Netscape was not open
861 Runtime.getRuntime().exec(new String[]
862 { (String) browser, url });
864 } catch (InterruptedException ie)
866 throw new IOException(MessageManager.formatMessage("exception.interrupted_launching_browser", new String[]{ie.getMessage()}));
873 // This should never occur, but if it does, we'll try the simplest thing
875 Runtime.getRuntime().exec(new String[]
876 { (String) browser, url });
883 * Methods required for Mac OS X. The presence of native methods does not
884 * cause any problems on other platforms.
886 private native static int ICStart(int[] instance, int signature);
888 private native static int ICStop(int[] instance);
890 private native static int ICLaunchURL(int instance, byte[] hint,
891 byte[] data, int len, int[] selectionStart, int[] selectionEnd);