com.isti.util
Class LaunchBrowser

java.lang.Object
  com.isti.util.LaunchBrowser

public class LaunchBrowser

extends java.lang.Object

Class LaunchBrowser contains methods for launching browser windows. Application and applet environments are supported. In an application environment, the operating system may be auto-determined and several different versions of the launch command may be attempted, including a user-specified launch command. The following default launch commands are used:

   Non-Windows:     netscape URL
   Windows95/98:    start "URL"
   Windows2000/XP:  cmd /C "start URL" (for non-file URLs)
   Windows2000/XP:  cmd /C "URL" (for file URLs)
   Macintosh:       /usr/bin/open URL
 

The order in which the launch commands are attempted is varied such that the one for the operating system in use is attempt first (after any 'setLaunchCommand()' entered). When using "start" or "cmd /C" under Windows operating systems, special characters ("&|()^") are "escaped" by preceding them with the carrot ("^") character.

Field Summary

protected java.applet.AppletContext	appletContextObj
protected boolean	browserLaunchEnabledFlag
protected static java.lang.String	CMDCQT_STR
protected static java.lang.String	EMPTY_STR
protected java.lang.String	errorMessage
protected java.lang.String[]	fileCmdPrefixArr
protected java.lang.String[]	fileCmdSuffixArr
protected java.lang.String[]	fileOsPrefixArr
protected java.lang.String[]	fileOsSuffixArr
protected int	firstCmdArrIdx
protected java.lang.String[]	httpCmdPrefixArr
protected java.lang.String[]	httpCmdSuffixArr
protected java.lang.String[]	httpOsPrefixArr
protected java.lang.String[]	httpOsSuffixArr
protected java.lang.String	lastShowURLCmdStr
static int	MACINTOSH Selection value to indicate Macintosh operating system.
protected static java.lang.String	NEED_ESC_CHARS
protected static java.lang.String	NETSCPSP_STR
static int	NON_WINDOWS Selection value to indicate non-Windows operating system.
protected static java.lang.String	osNamePropString
protected int	osSelectVal
protected static java.lang.String[]	osSelStringsArr
protected static java.lang.String	QUOTE_STR
protected static java.lang.String	STARTQT_STR
protected static java.lang.String	STARTSP_STR
protected static java.lang.String	UBOPENSP_STR
static int	WINDOWS_98 Selection value to indicate Windows 98 or earlier OS.
static int	WINDOWS_XP Selection value to indicate Windows XP/2000 operating system.

Constructor Summary

LaunchBrowser()
Creates a launch-browser object for an application environment.

LaunchBrowser(java.applet.Applet appletObj)
Creates a launch-browser object for an applet environment.

LaunchBrowser(java.applet.AppletContext appletContextObj)
Creates a launch-browser object for an applet environment.

LaunchBrowser(int selVal)
Creates a launch-browser object for an application environment.

LaunchBrowser(int selVal, java.lang.String cmdPrefixStr)
Creates a launch-browser object for an application environment.

LaunchBrowser(int selVal, java.lang.String cmdPrefixStr, java.lang.String cmdSuffixStr)
Creates a launch-browser object for an application environment.

LaunchBrowser(java.lang.String cmdPrefixStr)
Creates a launch-browser object for an application environment.

LaunchBrowser(java.lang.String cmdPrefixStr, java.lang.String cmdSuffixStr)
Creates a launch-browser object for an application environment.

Method Summary

void	clearErrorMessage() Clears the error message string.
static int	determineOSType() Determines the type of operating system in use.
static java.lang.String	escSpecialWinChars(java.lang.String urlStr) Scans the given URL string for special characters ("&|()^") and "escapes" them be preceding each one with the carrot ("^") character.
boolean	getErrorFlag() Returns true if an error was detected.
java.lang.String	getErrorMessage() Returns message string for last error (or 'No error' if none).
java.lang.String	getLastShowURLCmdStr() Returns the last command string used by the 'showURL()' (application mode) or 'showApplicationURL()' method.
java.lang.String	getOsNamePropString() Returns the Operating System name found in the "os.name" system property.
java.lang.String	getOSSelectString() Returns a description string for the operating system select value for this launch browser object ("Non-Windows", "Windows95/98", "Windows2000/XP" or "Macintosh").
int	getOSSelectVal() Returns the operating system select value for this launch browser object (NON_WINDOWS, WINDOWS_98, WINDOWS_XP or MACINTOSH).
java.lang.String	getPrefApplicationLaunchCmd(java.lang.String urlStr) Returns the "preferred" command that would be used to launch a browser for viewing a non-local-file URL in an application environment.
java.lang.String	getPrefApplicationLaunchFileCmd(java.lang.String urlStr) Returns the "preferred" command that would be used to launch a browser for viewing a local file in an application environment.
boolean	isEnabled() Returns an indicator of whether or not the launching of browser windows is enabled.
static boolean	isURLAddress(java.lang.String str) Returns true if the contents of the given string qualify as a valid URL address; otherwise returns false.
void	setEnabled(boolean flgVal) Enables or disables the launching of browser windows.
protected void	setErrorMessage(java.lang.String str) Enters error message.
void	setLaunchCommand(java.lang.String cmdPrefixStr) Sets up a preferred command used to launch the browser.
void	setLaunchCommand(java.lang.String cmdPrefixStr, boolean addSpaceFlag) Sets up a preferred command used to launch the browser.
void	setLaunchCommand(java.lang.String cmdPrefixStr, java.lang.String cmdSuffixStr) Sets up a preferred command used to launch the browser.
void	setLaunchCommand(java.lang.String cmdPrefixStr, java.lang.String cmdSuffixStr, boolean addSpaceFlag) Sets up a preferred command used to launch the browser.
void	setLaunchCommand(java.lang.String cmdPrefixStr, java.lang.String cmdSuffixStr, boolean httpCmdFlag, boolean fileCmdFlag) Sets up a preferred command used to launch the browser.
void	setLaunchCommand(java.lang.String cmdPrefixStr, java.lang.String cmdSuffixStr, boolean addSpaceFlag, boolean httpCmdFlag, boolean fileCmdFlag) Sets up a preferred command used to launch the browser.
boolean	setOSType(int selVal) Selects the operating system for this launch-browser object.
boolean	showAppletURL(java.lang.String urlStr) Displays the given URL address string in a browser window.
boolean	showAppletURL(java.lang.String urlStr, java.lang.String titleStr) Displays the given URL address string in a separate browser window.
boolean	showApplicationURL(java.lang.String urlStr) Displays the given URL address string in a new browser window.
boolean	showURL(java.lang.String urlStr) Displays the given URL address string in a browser window.
boolean	showURL(java.lang.String urlStr, java.lang.String titleStr) Displays the given URL address string in a browser window.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NON_WINDOWS

public static final int NON_WINDOWS

Selection value to indicate non-Windows operating system.

See Also:

Constant Field Values

WINDOWS_98

public static final int WINDOWS_98

Selection value to indicate Windows 98 or earlier OS.

See Also:

Constant Field Values

WINDOWS_XP

public static final int WINDOWS_XP

Selection value to indicate Windows XP/2000 operating system.

See Also:

Constant Field Values

MACINTOSH

public static final int MACINTOSH

Selection value to indicate Macintosh operating system.

See Also:

Constant Field Values

osSelStringsArr

protected static final java.lang.String[] osSelStringsArr

appletContextObj

protected final java.applet.AppletContext appletContextObj

osSelectVal

protected int osSelectVal

osNamePropString

protected static java.lang.String osNamePropString

errorMessage

protected java.lang.String errorMessage

NETSCPSP_STR

protected static java.lang.String NETSCPSP_STR

UBOPENSP_STR

protected static java.lang.String UBOPENSP_STR

STARTSP_STR

protected static java.lang.String STARTSP_STR

STARTQT_STR

protected static java.lang.String STARTQT_STR

CMDCQT_STR

protected static java.lang.String CMDCQT_STR

EMPTY_STR

protected static java.lang.String EMPTY_STR

QUOTE_STR

protected static java.lang.String QUOTE_STR

NEED_ESC_CHARS

protected static java.lang.String NEED_ESC_CHARS

httpOsPrefixArr

protected final java.lang.String[] httpOsPrefixArr

httpOsSuffixArr

protected final java.lang.String[] httpOsSuffixArr

fileOsPrefixArr

protected final java.lang.String[] fileOsPrefixArr

fileOsSuffixArr

protected final java.lang.String[] fileOsSuffixArr

httpCmdPrefixArr

protected java.lang.String[] httpCmdPrefixArr

httpCmdSuffixArr

protected java.lang.String[] httpCmdSuffixArr

fileCmdPrefixArr

protected java.lang.String[] fileCmdPrefixArr

fileCmdSuffixArr

protected java.lang.String[] fileCmdSuffixArr

firstCmdArrIdx

protected int firstCmdArrIdx

lastShowURLCmdStr

protected java.lang.String lastShowURLCmdStr

browserLaunchEnabledFlag

protected boolean browserLaunchEnabledFlag

Constructor Detail

LaunchBrowser

public LaunchBrowser()

Creates a launch-browser object for an application environment. The operating system type is automatically determined.

LaunchBrowser

public LaunchBrowser(java.lang.String cmdPrefixStr)

Creates a launch-browser object for an application environment. The operating system type is automatically determined.

Parameters:

cmdPrefixStr - the preferred string to put before the URL in the launch command, or null for none.

LaunchBrowser

public LaunchBrowser(java.lang.String cmdPrefixStr,
                     java.lang.String cmdSuffixStr)

Creates a launch-browser object for an application environment. The operating system type is automatically determined.

Parameters:

cmdPrefixStr - the preferred string to put before the URL in the launch command, or null for none.

cmdSuffixStr - the preferred string to put after the URL in the launch command, or null for none.

LaunchBrowser

public LaunchBrowser(int selVal)

Creates a launch-browser object for an application environment.

Parameters:

selVal - one of the operating system select values (NON_WINDOWS, WINDOWS_98, WINDOWS_XP or MACINTOSH).

LaunchBrowser

public LaunchBrowser(int selVal,
                     java.lang.String cmdPrefixStr)

Creates a launch-browser object for an application environment.

Parameters:

selVal - one of the operating system select values (NON_WINDOWS, WINDOWS_98, WINDOWS_XP or MACINTOSH).

cmdPrefixStr - the preferred string to put before the URL in the launch command, or null for none.

LaunchBrowser

public LaunchBrowser(int selVal,
                     java.lang.String cmdPrefixStr,
                     java.lang.String cmdSuffixStr)

Creates a launch-browser object for an application environment.

Parameters:

selVal - one of the operating system select values (NON_WINDOWS, WINDOWS_98, WINDOWS_XP or MACINTOSH).

cmdPrefixStr - the preferred string to put before the URL in the launch command, or null for none.

cmdSuffixStr - the preferred string to put after the URL in the launch command, or null for none.

LaunchBrowser

public LaunchBrowser(java.applet.AppletContext appletContextObj)

Creates a launch-browser object for an applet environment.

Parameters:

appletContextObj - the 'AppletContext' object to be used.

LaunchBrowser

public LaunchBrowser(java.applet.Applet appletObj)

Creates a launch-browser object for an applet environment.

Parameters:

appletObj - the 'Applet' object containing the 'AppletContext' object to be used.

Method Detail

setOSType

public boolean setOSType(int selVal)

Selects the operating system for this launch-browser object. Only used in application environment.

Parameters:

selVal - one of the operating system select values (NON_WINDOWS, WINDOWS_98, WINDOWS_XP or MACINTOSH).

Returns:

true if successful, false if invalid selection value.

setLaunchCommand

public void setLaunchCommand(java.lang.String cmdPrefixStr,
                             java.lang.String cmdSuffixStr,
                             boolean addSpaceFlag,
                             boolean httpCmdFlag,
                             boolean fileCmdFlag)

Sets up a preferred command used to launch the browser. Only used in application environment. A command suffix is provided to allow characters (such as a quote) to be placed at the end of the launch command. If both parameters are null then the default launch commands will be used.

Parameters:

cmdPrefixStr - the string put before the URL in the launch command, or null for none.

cmdSuffixStr - the string put after the URL in the launch command, or null for none.

addSpaceFlag - if true and the command prefix string ends with an alphanumeric or underscore character then a space is appended to the prefix.

httpCmdFlag - true to enter the given commands for use with non-file URLs.

fileCmdFlag - true to enter the given commands for use with local-file URLs.

setLaunchCommand

public void setLaunchCommand(java.lang.String cmdPrefixStr,
                             java.lang.String cmdSuffixStr,
                             boolean addSpaceFlag)

Sets up a preferred command used to launch the browser. Only used in application environment. A command suffix is provided to allow characters (such as a quote) to be placed at the end of the launch command. If both parameters are null then the default launch commands will be used.

Parameters:

cmdPrefixStr - the string put before the URL in the launch command, or null for none.

cmdSuffixStr - the string put after the URL in the launch command, or null for none.

addSpaceFlag - if true and the command prefix string ends with an alphanumeric or underscore character then a space is appended to the prefix.

setLaunchCommand

public void setLaunchCommand(java.lang.String cmdPrefixStr,
                             java.lang.String cmdSuffixStr,
                             boolean httpCmdFlag,
                             boolean fileCmdFlag)

Sets up a preferred command used to launch the browser. Only used in application environment. A command suffix is provided to allow characters (such as a quote) to be placed at the end of the launch command. If both parameters are null then the default launch commands will be used.

Parameters:

cmdPrefixStr - the string put before the URL in the launch command, or null for none.

cmdSuffixStr - the string put after the URL in the launch command, or null for none.

httpCmdFlag - true to enter the given commands for use with non-file URLs.

fileCmdFlag - true to enter the given commands for use with local-file URLs.

setLaunchCommand

public void setLaunchCommand(java.lang.String cmdPrefixStr,
                             java.lang.String cmdSuffixStr)

Sets up a preferred command used to launch the browser. Only used in application environment. A command suffix is provided to allow characters (such as a quote) to be placed at the end of the launch command. If both parameters are null then the default launch commands will be used. If the command prefix string ends with an alphanumeric or underscore character then a space is appended to the prefix.

Parameters:

cmdPrefixStr - the string put before the URL in the launch command, or null for none.

cmdSuffixStr - the string put after the URL in the launch command, or null for none.

setLaunchCommand

public void setLaunchCommand(java.lang.String cmdPrefixStr,
                             boolean addSpaceFlag)

Sets up a preferred command used to launch the browser. Only used in application environment.

Parameters:

cmdPrefixStr - the string put before the URL in the launch command, or null to have the default launch commands be used.

addSpaceFlag - if true and the command prefix string ends with an alphanumeric or underscore character then a space is appended to the prefix.

setLaunchCommand

public void setLaunchCommand(java.lang.String cmdPrefixStr)

Sets up a preferred command used to launch the browser. Only used in application environment. If the command prefix string ends with an alphanumeric or underscore character then a space is appended to the prefix.

Parameters:

cmdPrefixStr - the string put before the URL in the launch command, or null to have the default launch commands be used.

showApplicationURL

public boolean showApplicationURL(java.lang.String urlStr)

Displays the given URL address string in a new browser window. Only used in application environment.

Parameters:

urlStr - a string containing the URL.

Returns:

true if successful; false if error (in which case an error message may be fetched via the 'getErrorMessage()' method).

getPrefApplicationLaunchCmd

public java.lang.String getPrefApplicationLaunchCmd(java.lang.String urlStr)

Returns the "preferred" command that would be used to launch a browser for viewing a non-local-file URL in an application environment. Note that the 'showURL()' method may also revert to using a default launch command if the preferred command fails.

Parameters:

urlStr - the URL string to use in the command.

Returns:

The launch-browser command.

getPrefApplicationLaunchFileCmd

public java.lang.String getPrefApplicationLaunchFileCmd(java.lang.String urlStr)

Returns the "preferred" command that would be used to launch a browser for viewing a local file in an application environment. Note that the 'showURL()' method may also revert to using a default launch command if the preferred command fails.

Parameters:

urlStr - the URL string to use in the command.

Returns:

The launch-browser command.

getLastShowURLCmdStr

public java.lang.String getLastShowURLCmdStr()

Returns the last command string used by the 'showURL()' (application mode) or 'showApplicationURL()' method.

Returns:

The last command string used by the 'showURL()' (application mode) or 'showApplicationURL()' method, or null if none available.

showAppletURL

public boolean showAppletURL(java.lang.String urlStr,
                             java.lang.String titleStr)

Displays the given URL address string in a separate browser window.

Parameters:

urlStr - a string containing the URL.

titleStr - a string used to select a target browser window.

Returns:

true if successful; false if error (in which case an error message may be fetched via the 'getErrorMessage()' method).

showAppletURL

public boolean showAppletURL(java.lang.String urlStr)

Displays the given URL address string in a browser window.

Parameters:

urlStr - a string containing the URL.

Returns:

true if successful; false if error (in which case an error message may be fetched via the 'getErrorMessage()' method).

showURL

public boolean showURL(java.lang.String urlStr,
                       java.lang.String titleStr)

Displays the given URL address string in a browser window. This method calls either the 'showAppletURL()' or 'showApplicationURL()' method, depending on how this object was constructed.

Parameters:

urlStr - a string containing the URL.

titleStr - a string used to select a target browser window.

Returns:

true if successful; false if error (in which case an error message may be fetched via the 'getErrorMessage()' method).

showURL

public boolean showURL(java.lang.String urlStr)

Displays the given URL address string in a browser window. This method calls either the 'showAppletURL()' or 'showApplicationURL()' method, depending on how this object was constructed.

Parameters:

urlStr - a string containing the URL.

Returns:

true if successful; false if error (in which case an error message may be fetched via the 'getErrorMessage()' method).

setEnabled

public void setEnabled(boolean flgVal)

Enables or disables the launching of browser windows. The default state is 'enabled'.

Parameters:

flgVal - true to enable, false to disable.

isEnabled

public boolean isEnabled()

Returns an indicator of whether or not the launching of browser windows is enabled.

Returns:

true if enabled, false if disabled.

setErrorMessage

protected void setErrorMessage(java.lang.String str)

Enters error message.

Parameters:

str - error message string.

getErrorFlag

public boolean getErrorFlag()

Returns true if an error was detected. The error message may be fetched via the 'getErrorMessage()' method.

Returns:

true if an error was detected.

getErrorMessage

public java.lang.String getErrorMessage()

Returns message string for last error (or 'No error' if none).

Returns:

message string for last error (or 'No error' if none).

clearErrorMessage

public void clearErrorMessage()

Clears the error message string.

getOSSelectVal

public int getOSSelectVal()

Returns the operating system select value for this launch browser object (NON_WINDOWS, WINDOWS_98, WINDOWS_XP or MACINTOSH).

Returns:

the operating system select value for this launch browser object (NON_WINDOWS, WINDOWS_98, WINDOWS_XP or MACINTOSH).

getOSSelectString

public java.lang.String getOSSelectString()

Returns a description string for the operating system select value for this launch browser object ("Non-Windows", "Windows95/98", "Windows2000/XP" or "Macintosh").

Returns:

a description string for the operating system select value for this launch browser object ("Non-Windows", "Windows95/98", "Windows2000/XP" or "Macintosh").

getOsNamePropString

public java.lang.String getOsNamePropString()

Returns the Operating System name found in the "os.name" system property.

Returns:

The name of the current operating system, or an empty string if the name could not be fetched.

determineOSType

public static int determineOSType()

Determines the type of operating system in use.

Returns:

one of the operating system select values (NON_WINDOWS, WINDOWS_98, WINDOWS_XP or MACINTOSH).

isURLAddress

public static boolean isURLAddress(java.lang.String str)

Returns true if the contents of the given string qualify as a valid URL address; otherwise returns false. If the string begins with 1 to 10 letters (or digits) followed by "://" then it is considered a valid URL address.

Parameters:

str - the string to check.

Returns:

true if the contents of the given string qualify as a valid URL address; otherwise false.

escSpecialWinChars

public static java.lang.String escSpecialWinChars(java.lang.String urlStr)

Scans the given URL string for special characters ("&|()^") and "escapes" them be preceding each one with the carrot ("^") character. These special characters need to be "escaped" when a parameter is sent to a Windows command interpreter.

Parameters:

urlStr - string to scan.

Returns:

The given string with special characters "escaped", or the original given string if no special characters were found.