Poseidon for UMLTM
  UMLdoc
 PREV  CLASSIFIER    NEXT  CLASSIFIER     FRAMES    NO FRAMES      
SUMMARY:   INNER | ATTR | ASSOC | CONSTR | METHOD     DETAIL:   INNER | ATTR | ASSOC | CONSTR | METHOD     DIAGRAMS:   COLLAB | SEQ | STATE | ACTIV

com.gentleware.services.util

Class BrowserLauncher

com.gentleware.services.util.BrowserLauncher

public class BrowserLauncher


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 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.

Credits:
Steven Spencer, JavaWorld magazine (Java">http://www.javaworld.com/javaworld/javatips/jw-javatip66.html">Java Tip 66)
Ron B. Yeh, ZeroG
Ben Engber, The New York Times
Paul Teitlebaum and Andrea Cantatore, Datatech Software

Version:
1.2 (Released July 28, 1999)


 Attribute Summary
private static String  FINDER_CREATOR
The creator code of the Finder on a Macintosh, which is needed to send AppleEvents to the application. 
private static String  FINDER_TYPE
The file type of the Finder on a Macintosh. 
private static 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 String  GURL_EVENT
The name for the AppleEvent type corresponding to a GetURL event. 
private static String  JDirect_MacOSX
The framework to reference on Mac OS X  
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 int  OTHER
JVM constant for any other platform  
private static String  SECOND_WINDOWS_PARAMETER
The second parameter for Runtime.exec() on Windows. 
private static 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  
private static Object  _browser
The _browser for the system  
public static HyperlinkListener  _hyperLinkListener
A hyperlink listener that uses the BrowserLauncher to show urls  
private static Class  aeDescClass
The com.apple.MacOS.AEDesc class  
private static Constructor  aeDescConstructor
The (String) method of com.apple.MacOS.AEDesc  
private static Constructor  aeTargetConstructor
The (int) method of com.apple.MacOS.AETarget  
private static Constructor  appleEventConstructor
The (int, int, int) method of com.apple.MacOS.AppleEvent  
private static String  errorMessage
The message from any exception thrown throughout the initialization process. 
private static Method  findFolder
The findFolder method of com.apple.mrj.MRJFileUtils  
private static Method  getFileCreator
The getFileCreator method of com.apple.mrj.MRJFileUtils  
private static Method  getFileType
The getFileType method of com.apple.mrj.MRJFileUtils  
private static int  jvm
The Java virtual machine that we are running on. 
private static Integer  kAnyTransactionID
The kAnyTransactionID AppleEvent code  
private static Integer  kAutoGenerateReturnID
The kAutoGenerateReturnID AppleEvent code  
private static Object  kSystemFolderType
Actually an MRJOSType pointing to the System Folder on a Macintosh  
private static Integer  keyDirectObject
The keyDirectObject AppleEvent parameter type  
private static 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 Method  makeOSType
The makeOSType method of com.apple.MacOS.OSUtils  
private static Class  mrjFileUtilsClass
The com.apple.mrj.MRJFileUtils class  
private static Class  mrjOSTypeClass
The com.apple.mrj.MRJOSType class  
private static Method  openURL
The openURL method of com.apple.mrj.MRJFileUtils  
private static Method  putParameter
The putParameter method of com.apple.MacOS.AppleEvent  
private static Method  sendNoReply
The sendNoReply method of com.apple.MacOS.AppleEvent  
arrow_up
 

 Constructor Summary
private   BrowserLauncher()
An initialization block that determines the operating system and loads the necessary runtime data. 
arrow_up
 

 Method Summary
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 void   __initializer()
 
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 Object   locateBrowser()
Attempts to locate the default web _browser on the local system. 
private static void   openURL(String url, Object browser)
Attempts to open the default web _browser to the given URL. 
public static boolean   showURL(URL url)
 
public static boolean   showURL(String urlString)
 
public static boolean   showURL(String urlString, Object browser)
 
private static void   tryUnix(String browser, String url)
 
arrow_up
 

Tagged Values
static false
gentleware-imported-line-number 60
gentleware-imported-package-statement-line-number 44
 

 Attribute Detail

FINDER_CREATOR

private static String FINDER_CREATOR

The creator code of the Finder on a Macintosh, which is needed to send AppleEvents to the application.  
arrow_up


FINDER_TYPE

private static String FINDER_TYPE

The file type of the Finder on a Macintosh. Hardcoding "Finder" would keep non-U.S. English systems from working properly.  
arrow_up


FIRST_WINDOWS_PARAMETER

private static String FIRST_WINDOWS_PARAMETER

The first parameter that needs to be passed into Runtime.exec() to open the default web _browser on Windows.  
arrow_up


GURL_EVENT

private static String GURL_EVENT

The name for the AppleEvent type corresponding to a GetURL event.  
arrow_up


JDirect_MacOSX

private static String JDirect_MacOSX

The framework to reference on Mac OS X  
arrow_up


MRJ_2_0

private static int MRJ_2_0

JVM constant for MRJ 2.0  
arrow_up


MRJ_2_1

private static int MRJ_2_1

JVM constant for MRJ 2.1 or later  
arrow_up


MRJ_3_0

private static int MRJ_3_0

JVM constant for Java on Mac OS X 10.0 (MRJ 3.0)  
arrow_up


MRJ_3_1

private static int MRJ_3_1

JVM constant for MRJ 3.1  
arrow_up


OTHER

private static int OTHER

JVM constant for any other platform  
arrow_up


SECOND_WINDOWS_PARAMETER

private static String SECOND_WINDOWS_PARAMETER

The second parameter for Runtime.exec() on Windows.  
arrow_up


THIRD_WINDOWS_PARAMETER

private static 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.  
arrow_up


WINDOWS_9x

private static int WINDOWS_9x

JVM constant for any Windows 9x JVM  
arrow_up


WINDOWS_NT

private static int WINDOWS_NT

JVM constant for any Windows NT JVM  
arrow_up


_browser

private static Object _browser

The _browser for the system  
arrow_up


_hyperLinkListener

public static HyperlinkListener _hyperLinkListener

A hyperlink listener that uses the BrowserLauncher to show urls  
arrow_up


aeDescClass

private static Class aeDescClass

The com.apple.MacOS.AEDesc class  
arrow_up


aeDescConstructor

private static Constructor aeDescConstructor

The (String) method of com.apple.MacOS.AEDesc  
arrow_up


aeTargetConstructor

private static Constructor aeTargetConstructor

The (int) method of com.apple.MacOS.AETarget  
arrow_up


appleEventConstructor

private static Constructor appleEventConstructor

The (int, int, int) method of com.apple.MacOS.AppleEvent  
arrow_up


errorMessage

private static String errorMessage

The message from any exception thrown throughout the initialization process.  
arrow_up


findFolder

private static Method findFolder

The findFolder method of com.apple.mrj.MRJFileUtils  
arrow_up


getFileCreator

private static Method getFileCreator

The getFileCreator method of com.apple.mrj.MRJFileUtils  
arrow_up


getFileType

private static Method getFileType

The getFileType method of com.apple.mrj.MRJFileUtils  
arrow_up


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.  
arrow_up


kAnyTransactionID

private static Integer kAnyTransactionID

The kAnyTransactionID AppleEvent code  
arrow_up


kAutoGenerateReturnID

private static Integer kAutoGenerateReturnID

The kAutoGenerateReturnID AppleEvent code  
arrow_up


kSystemFolderType

private static Object kSystemFolderType

Actually an MRJOSType pointing to the System Folder on a Macintosh  
arrow_up


keyDirectObject

private static Integer keyDirectObject

The keyDirectObject AppleEvent parameter type  
arrow_up


linkage

private static Object linkage

The linkage object required for JDirect 3 on Mac OS X.  
arrow_up


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.  

arrow_up


makeOSType

private static Method makeOSType

The makeOSType method of com.apple.MacOS.OSUtils  
arrow_up


mrjFileUtilsClass

private static Class mrjFileUtilsClass

The com.apple.mrj.MRJFileUtils class  
arrow_up


mrjOSTypeClass

private static Class mrjOSTypeClass

The com.apple.mrj.MRJOSType class  
arrow_up


openURL

private static Method openURL

The openURL method of com.apple.mrj.MRJFileUtils  
arrow_up


putParameter

private static Method putParameter

The putParameter method of com.apple.MacOS.AppleEvent  
arrow_up


sendNoReply

private static Method sendNoReply

The sendNoReply method of com.apple.MacOS.AppleEvent  
arrow_up
 Constructor Detail

BrowserLauncher

private com.gentleware.services.util.BrowserLauncher BrowserLauncher()


An initialization block that determines the operating system and loads the necessary runtime data.  
Returns:
arrow_up
 Method Detail

ICLaunchURL

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

Parameters:
instance -
hint -
data -
len -
selectionStart -
selectionEnd -
Returns:
arrow_up


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.  
Parameters:
instance -
signature -
Returns:
arrow_up


ICStop

private static int ICStop(int[] instance)

Parameters:
instance -
Returns:
arrow_up


__initializer

private static void __initializer()

arrow_up


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
arrow_up


locateBrowser

private static 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.
arrow_up


openURL

private static void openURL(String url, Object browser)


Attempts to open the default web _browser to the given URL.  
Parameters:
url - The URL to open
browser -
Exceptions:
IOException If the web _browser could not be located or does not run
arrow_up


showURL

public static boolean showURL(URL url)

Parameters:
url -
Returns:
arrow_up


showURL

public static boolean showURL(String urlString)

Parameters:
urlString -
Returns:
arrow_up


showURL

public static boolean showURL(String urlString, Object browser)

Parameters:
urlString -
browser -
Returns:
arrow_up


tryUnix

private static void tryUnix(String browser, String url)

Parameters:
browser -
url -
arrow_up
Created  2004 - 12 - 1

    Poseidon for UMLTM
  UMLdoc
 PREV  CLASSIFIER    NEXT  CLASSIFIER     FRAMES    NO FRAMES      
SUMMARY:   INNER | ATTR | ASSOC | CONSTR | METHOD     DETAIL:   INNER | ATTR | ASSOC | CONSTR | METHOD     DIAGRAMS:   COLLAB | SEQ | STATE | ACTIV

Generated with Poseidon for UMLTM.
Poseidon is a registered trademark of Gentleware AG in Germany, USA and other countries. Copyright 2003-2004 Gentleware AG, Schanzenstr. 70, 20357 Hamburg, Germany. All Rights Reserved.

UML is a trademark or registered trademark of Object Management Group, Inc. in the U.S. and other countries.