ca.bc.webarts.tools
Class AutoUpdateApp

java.lang.Object
  extended byca.bc.webarts.tools.AutoUpdateApp
Direct Known Subclasses:
JOggPlayerAutoUpdating

public class AutoUpdateApp
extends java.lang.Object

This is a self standing Java application that acts as a middleware application executor that lets you put this class and a properties file on a client and be able to execute anything you want and have it update the app automatically from a specified URL. A static method is also available to access the functionality from within existing code.

It executes applications... both native or Java as specified in a Properties file that gets passed to it (via a filename on the commandline). All system output from the executed app is echoed to the System.out (both regular and error output).

Its main purpose is to provide a single entrypoint to execute applications that can be dynamically specified at runtime. This allows a single deployment of this class onto a client and then tell this class what to run and where to download an update from if needed.

If you want this class to have a the name of your app; just extend this class and name it what you want... like the JOggPlayeAutoUpdate.java file.

Features:

Usage:
java AutoUpdateApp < propertiesFilename> OR
java -jar AutoUpdateApp.jar <propertiesFilename>

The properties file describes the app to execute. It has both required and optional entries as follows:


An Example Properties file might look like:

 # NATIVE Remote Application Description property file
 appType=0
 remoteAppURL=file:/c:/progra~1/tn.bat
 #remoteAppURL=c:\\progra~1\\tn.bat
 remoteAppDownloadURL=
 remoteAppAutoDownload=false
 telnetHost=10.0.0.22 2020
 

OR

 # Java Remote Application Description property file
 appType=1
 remoteAppURL=SimpleExample
 remoteAppDownloadURL=http://somesite.com/updates/MySimpleExample.jar
 remoteAppAutoDownload=false
 remoteAppJvmParameters=-Xmx64m
 extraParm=myParm1
 anotherExtraParm=myParm2
 
OR
 # Java Remote Application Description property file
 appType=1
 remoteAppURL=TelnetApp.jar
 remoteAppDownloadURL=http://somesite.com/updates/TelnetApp.jar
 remoteAppAutoDownload=true
 remoteAppJvmClasspath=/usr/local/extraclasses.jar;/usr/moreextraclasses.jar
 telnetHost=10.0.0.22 2020
 

Author: Tom Gutwin P.Eng.
Copyright (C) 2002-2003 WebARTS Design, North Vancouver Canada. All Rights Reserved.

Author:
Tom Gutwin P.Eng.

Field Summary
static java.lang.String APPLET_APP
          Class Constant specifying that the app to run is a Java Applet
protected static java.lang.String appName_
          This var should be defined by an extending class (not required)
protected static java.lang.String appPropertyFilename_
          The default property filename to use.
private static java.lang.String appType_
          Remote Launch Parm specifying the remote lauch app type (required).
private static boolean archiveDownload_
          A class var to indicate if the download URL is pointing to an archive file (ie jar file) instead of the actual executable file.
private static java.lang.String archiveFilePath_
          The system dependant file path for the downloaded archive file.
(package private) static java.lang.String CLASSPATH
          this VM classpath
private static java.util.Vector cmdLineParms_
          A table of strings holding any extra parameter properties that were passed in the properties file.
private static java.lang.String DEFAULT_SAVE_LOCATION
          A holder for the directory location to save downloaded apps.
private static java.util.Vector definedPropertyKeys
          A helper Vector that keeps a table of the Defined Properties.
private static java.lang.String errorMsg_
          A class var to record and error message to print out if any of the validation checks on the properties fail.
private static java.lang.String filePath_
          The system dependant file path to execute.
static java.lang.String HTTPURL_APP
          Class Constant specifying that the app to run is a URL Locationto view using the native webbrowser.
static java.lang.String JAVA_APP
          Class Constant specifying that the app to run is a Java application
private static java.lang.String jvmClasspath_
          Remote Launch Parm specifying the any extra classpath parms to put at the front of the classpath when the calling the jvm.
private static java.lang.String jvmParameters_
          Remote Launch Parm specifying the any extra commandline parms to send directly to the jvm.
static java.lang.String NATIVE_APP
          Class Constant specifying that the app to run is a native application
private static boolean remoteAppAutoDownload_
          Remote Launch Parm specifying the flag (boolean string val) that specifies if the RemoteLaunchOperation Operation should query the download server for updated app files.
private static java.net.URL remoteAppDownloadURL_
          Remote Launch Parm specifying the URL of the download for the Remote Launch APP.
private static java.net.URL remoteAppURL_
          Remote Launch Parm specifying the remote lauched application in the form of a URL.
static java.lang.String RMT_APP_AUTODOWNLOAD
          Remote Launch Property Key specifying the flag (boolean string value) that specifies if the RemoteLaunchOperation Operation should query the download server for updated app files.
static java.lang.String RMT_APP_DOWNLOADURL
          Remote Launch Property Key specifying the URL of the download for the Remote Launch APP.
static java.lang.String RMT_APP_JVM_CLASSPATH
          Remote Launch Property Key specifying any parameters that should be added to the FRONT of the classpath when executing a Java App.
static java.lang.String RMT_APP_JVM_PARAMETERS
          Remote Launch Property Key specifying any parameters that should go to the JVM when executing a Java App.
static java.lang.String RMT_APP_TYPE
          Remote Launch Property Key specifying the remote lauch app type.
static java.lang.String RMT_APP_URL
          Remote Launch Property Key specifying the remote lauch URL for the RemoteLaunchOperation.HTTPURL_APP app type.
private static boolean soFarSoGood_
          A class var to track the progress of the various validation checks that are performed.
private static java.lang.String SYSTEM_FILE_SEPERATOR
          A holder for the NA Clients System File Separator.
 
Constructor Summary
protected AutoUpdateApp()
          Basic constructor for the application.
 
Method Summary
private static boolean checkAndUpdateApp(java.net.URL urlToGet)
          Checks the specified remoteAppDownloadURL_ to see if there is a newer version of the remoteAppURL_ AND then goes out and updates the app if a newer one is available.
private static boolean checkForUpdatedApp()
          Checks the specified remoteAppDownloadURL_ to see if there is a newer version of the remoteAppURL_.
static java.lang.String convertSystemDependantPath(java.net.URL url)
          Converts the path component of a URL to the native relative file path.
private static boolean ensureTheAppIsAvailable(java.lang.String filePath)
          This helper method checks that the specified file exists, if not it downloads it from the download URL.
private static int execute()
          Determines the app type that has been assigned to the class variables and calls the correct helper method that Executes the class defined remote app.
protected static int executeJavaApp(java.lang.String classLocation, java.util.Vector appParms)
          Executes the Specified Java appilcation with the provided commandline parameters.
protected static int executeJavaApp(java.lang.String classLocation, java.util.Vector jvmParms, java.util.Vector appParms)
          Executes the Specified Java appilcation with the provided JVM parameters and executableApp commandline parameters.
static int executeNativeApp(java.lang.String executableLocation, java.lang.String[] cmdParms)
          Executes the Specified Native OS application with the provided commandline parameters.
static int executeNativeApp(java.lang.String executableLocation, java.lang.String[] cmdParms, java.lang.String outputFilename)
          Executes the Specified Native OS application with the provided commandline parameters.
protected static int executeNativeApp(java.lang.String executableLocation, java.util.Vector appParms)
          Executes the Specified Native OS application with the provided commandline parameters.
private static java.lang.String getFilePathFromClasspath(java.lang.String filename)
          Searches the classpath for the specified filename and then returns the full path that is used for it.
private static boolean initialize(java.util.Properties props)
          Initializes the apps vars (based on the passed in properties file) and gets ready to start.
protected static java.util.Properties loadAutoAppPropertiesFile()
          Loads the AutoDownload app information from the properties file so this wrapped app can execute.
protected static java.util.Properties loadPropertiesFile(java.lang.String propFilename)
          Loads the passed Properties file and returns a Properties object.
static void main(java.lang.String[] args)
          The main entry for this app.
private static java.net.URL parseAppExecutableUrl(java.lang.String value)
          Parses a String representation of a URL or absolute file path and converts it into a URL.
private static boolean parseProperties(java.util.Properties props)
          Parses the passed in Properties and pulls out all the name/value pairs and assigns them to the class vars as needed.
static int runApp(java.util.Properties props)
          The entry point for running an app defined by the passed in properties.
private static boolean updateAppFromServer(java.net.URL urlToGet)
          Downloads the requested URL and replaces any existing version.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

appName_

protected static java.lang.String appName_
This var should be defined by an extending class (not required)


appPropertyFilename_

protected static java.lang.String appPropertyFilename_
The default property filename to use.


CLASSPATH

static final java.lang.String CLASSPATH
this VM classpath


NATIVE_APP

public static final java.lang.String NATIVE_APP
Class Constant specifying that the app to run is a native application

See Also:
Constant Field Values

JAVA_APP

public static final java.lang.String JAVA_APP
Class Constant specifying that the app to run is a Java application

See Also:
Constant Field Values

APPLET_APP

public static final java.lang.String APPLET_APP
Class Constant specifying that the app to run is a Java Applet

See Also:
Constant Field Values

HTTPURL_APP

public static final java.lang.String HTTPURL_APP
Class Constant specifying that the app to run is a URL Locationto view using the native webbrowser.

See Also:
Constant Field Values

RMT_APP_TYPE

public static final java.lang.String RMT_APP_TYPE
Remote Launch Property Key specifying the remote lauch app type.

This is a required property in the supplied properties file.

See Also:
Constant Field Values

RMT_APP_URL

public static final java.lang.String RMT_APP_URL
Remote Launch Property Key specifying the remote lauch URL for the RemoteLaunchOperation.HTTPURL_APP app type.

This is a required property in the supplied properties file.

See Also:
Constant Field Values

RMT_APP_DOWNLOADURL

public static final java.lang.String RMT_APP_DOWNLOADURL
Remote Launch Property Key specifying the URL of the download for the Remote Launch APP.

This is an optional property in the supplied properties file.

See Also:
Constant Field Values

RMT_APP_AUTODOWNLOAD

public static final java.lang.String RMT_APP_AUTODOWNLOAD
Remote Launch Property Key specifying the flag (boolean string value) that specifies if the RemoteLaunchOperation Operation should query the download server for updated app files.

This is an optional property in the supplied properties file. (default=true)

See Also:
Constant Field Values

RMT_APP_JVM_PARAMETERS

public static final java.lang.String RMT_APP_JVM_PARAMETERS
Remote Launch Property Key specifying any parameters that should go to the JVM when executing a Java App.

This is an optional property in the supplied properties file. (default="")

See Also:
Constant Field Values

RMT_APP_JVM_CLASSPATH

public static final java.lang.String RMT_APP_JVM_CLASSPATH
Remote Launch Property Key specifying any parameters that should be added to the FRONT of the classpath when executing a Java App.

This is an optional property in the supplied properties file. (default="")

A StringTokenizer is used to parse this property value and usessemi colons or colons as delimiters. Note that spaces are NOT used as delimeters so they can be used in the paths.

See Also:
Constant Field Values

definedPropertyKeys

private static java.util.Vector definedPropertyKeys
A helper Vector that keeps a table of the Defined Properties.


SYSTEM_FILE_SEPERATOR

private static final java.lang.String SYSTEM_FILE_SEPERATOR
A holder for the NA Clients System File Separator.


DEFAULT_SAVE_LOCATION

private static final java.lang.String DEFAULT_SAVE_LOCATION
A holder for the directory location to save downloaded apps.

Default = ./RemoteApps/ (or the DOS Equiv. .\RemoteApps\).


appType_

private static java.lang.String appType_
Remote Launch Parm specifying the remote lauch app type (required).


remoteAppURL_

private static java.net.URL remoteAppURL_
Remote Launch Parm specifying the remote lauched application in the form of a URL.

It gets assigned from the required property RMT_APP_URL in the supplied properties file.


filePath_

private static java.lang.String filePath_
The system dependant file path to execute.


archiveFilePath_

private static java.lang.String archiveFilePath_
The system dependant file path for the downloaded archive file.


remoteAppDownloadURL_

private static java.net.URL remoteAppDownloadURL_
Remote Launch Parm specifying the URL of the download for the Remote Launch APP.


remoteAppAutoDownload_

private static boolean remoteAppAutoDownload_
Remote Launch Parm specifying the flag (boolean string val) that specifies if the RemoteLaunchOperation Operation should query the download server for updated app files.

(default=true)


jvmParameters_

private static java.lang.String jvmParameters_
Remote Launch Parm specifying the any extra commandline parms to send directly to the jvm.

(default="")


jvmClasspath_

private static java.lang.String jvmClasspath_
Remote Launch Parm specifying the any extra classpath parms to put at the front of the classpath when the calling the jvm.

(default="")

A StringTokenizer is used to parse this property value. So commas or a space delimited list of entries will work.


soFarSoGood_

private static boolean soFarSoGood_
A class var to track the progress of the various validation checks that are performed.


archiveDownload_

private static boolean archiveDownload_
A class var to indicate if the download URL is pointing to an archive file (ie jar file) instead of the actual executable file.

This field gets used by the updateAppFromServer method to determine where to save the file.

See Also:
updateAppFromServer(java.net.URL)

errorMsg_

private static java.lang.String errorMsg_
A class var to record and error message to print out if any of the validation checks on the properties fail.


cmdLineParms_

private static java.util.Vector cmdLineParms_
A table of strings holding any extra parameter properties that were passed in the properties file. Extra means anything that do not match any of the Keys specified above.

Constructor Detail

AutoUpdateApp

protected AutoUpdateApp()
Basic constructor for the application. It is empty. The entry for this app is the main( String[] ) or runApp(Properties)methods.

See Also:
main(java.lang.String[]), runApp(java.util.Properties)
Method Detail

runApp

public static int runApp(java.util.Properties props)
The entry point for running an app defined by the passed in properties.

This method blocks until the Executed app is complete

Parameters:
props - the Properties defining the app to run as defined in the main class description.
Returns:
the return code from the exec'd application, -1 if the app did not get executed or the app returned a -1.
See Also:
main(java.lang.String[])

main

public static void main(java.lang.String[] args)
The main entry for this app. It performs all the calls to validate, download and then execute the executable requested in the Properties file that is passed in as this apps single commandline parameter.

Parameters:
args - are the commandline parameters.This app expects ONLY 1 parameter... the absolute file path to the properties file containing all the info for the Remote App to execute.
See Also:
runApp(java.util.Properties)

initialize

private static boolean initialize(java.util.Properties props)
Initializes the apps vars (based on the passed in properties file) and gets ready to start.

Returns:
true if everything went okay and we can now start

ensureTheAppIsAvailable

private static boolean ensureTheAppIsAvailable(java.lang.String filePath)
This helper method checks that the specified file exists, if not it downloads it from the download URL.

Returns:
true if everything went okay and we have the file in place.

getFilePathFromClasspath

private static java.lang.String getFilePathFromClasspath(java.lang.String filename)
Searches the classpath for the specified filename and then returns the full path that is used for it.

Returns:
the path description of the passed filename as found in the classpath.

convertSystemDependantPath

public static java.lang.String convertSystemDependantPath(java.net.URL url)
Converts the path component of a URL to the native relative file path.

Parameters:
url - the url to use to convert.
Returns:
the converted path string. It will return a "" if the URL does not include a filepath portion.

execute

private static int execute()
Determines the app type that has been assigned to the class variables and calls the correct helper method that Executes the class defined remote app. It Expects that all the class vars that desribe the app are in place and valid.


parseAppExecutableUrl

private static java.net.URL parseAppExecutableUrl(java.lang.String value)
                                           throws java.net.MalformedURLException
Parses a String representation of a URL or absolute file path and converts it into a URL.

This method is a bit forgiving... if the string is not a correctlty formatted http, ftp, or file URL it will assume it is a file URL and create the returned URL as such.

Parameters:
value - is the String to convert into a URL.
Returns:
the Valid URL for the Executable or null if this method failed to convert the passed in string.
Throws:
java.net.MalformedURLException - if the passed in String is not a URL

checkAndUpdateApp

private static boolean checkAndUpdateApp(java.net.URL urlToGet)
Checks the specified remoteAppDownloadURL_ to see if there is a newer version of the remoteAppURL_ AND then goes out and updates the app if a newer one is available.

Parameters:
urlToGet - is the place to go to get the updated app.
Returns:
true if there is a newer version available and it was download successfully.
See Also:
remoteAppDownloadURL_, remoteAppURL_

checkForUpdatedApp

private static boolean checkForUpdatedApp()
Checks the specified remoteAppDownloadURL_ to see if there is a newer version of the remoteAppURL_.

Returns:
true if there is a newer version available
See Also:
checkAndUpdateApp(java.net.URL), remoteAppDownloadURL_, remoteAppURL_

updateAppFromServer

private static boolean updateAppFromServer(java.net.URL urlToGet)
Downloads the requested URL and replaces any existing version.

The place for saving this downloaded file is determined based on the archiveDownload_ flag. If archiveDownload_is true then dowloaded file is saved as a new /updated file with its own filename. This is done when an archive file is used as the download that is not the same as the executable name found in the remoteAppURL_ field. For example: if remoteAppURL_ points to ca.bc.webarts.SomeClass and the remoteAppDownloadURL_ points to SomeClass.jar we need to save the downloaded file to SomeClass.jar and then assume the commandline parameters will take care of the running/classpath issues.

Parameters:
urlToGet - is the place to go to get the updated app.
Returns:
true if successfully updated
See Also:
archiveDownload_

executeNativeApp

protected static int executeNativeApp(java.lang.String executableLocation,
                                      java.util.Vector appParms)
Executes the Specified Native OS application with the provided commandline parameters. This method blocks until the Executed app is complete. It also cleans up its sub-process and garbage collects.
NOTE: This method uses a vector for the appParams and DOES NOT guaranty parameter order. Please use the executeNativeApp(String executableLocation, String [] cmdParms) method\ which uses an array for storage/retreival of the app parms.

Parameters:
executableLocation - is the path to the executable to run
appParms - and extra commandline parameters to tag onto the end of the commandline that gets executed.
Returns:
returns the return code from the executed app/process
See Also:
executeNativeApp(java.lang.String, java.lang.String[]), StreamGobbler, Runtime.getRuntime()

executeNativeApp

public static int executeNativeApp(java.lang.String executableLocation,
                                   java.lang.String[] cmdParms)
Executes the Specified Native OS application with the provided commandline parameters. This method blocks until the Executed app is complete. It also cleans up its sub-process and garbage collects. This method sends app output to std out.

Parameters:
executableLocation - is the path to the executable to run
cmdParms - and extra commandline parameters to tag onto the end of the commandline that gets executed.
Returns:
returns the return code from the executed app/process
See Also:
StreamGobbler, Runtime.getRuntime()

executeNativeApp

public static int executeNativeApp(java.lang.String executableLocation,
                                   java.lang.String[] cmdParms,
                                   java.lang.String outputFilename)
Executes the Specified Native OS application with the provided commandline parameters. This method blocks until the Executed app is complete. It also cleans up its sub-process and garbage collects.

Parameters:
executableLocation - is the path to the executable to run
cmdParms - and extra commandline parameters to tag onto the end of the commandline that gets executed.
outputFilename - a filename to send the output to.
Returns:
returns the return code from the executed app/process
See Also:
StreamGobbler, Runtime.getRuntime()

executeJavaApp

protected static int executeJavaApp(java.lang.String classLocation,
                                    java.util.Vector appParms)
Executes the Specified Java appilcation with the provided commandline parameters.

Parameters:
classLocation - is the path to the executable to run
appParms - and extra commandline parameters to tag onto the end of the commandline that gets executed.
Returns:
returns the return code from the executed app/process

executeJavaApp

protected static int executeJavaApp(java.lang.String classLocation,
                                    java.util.Vector jvmParms,
                                    java.util.Vector appParms)
Executes the Specified Java appilcation with the provided JVM parameters and executableApp commandline parameters.

Parameters:
classLocation - is the path to the executable to run
jvmParms - holds any cmdline parms to send directly to the jvm
appParms - and extra commandline parameters to tag onto the end of the commandline that gets executed.
Returns:
returns the return code from the executed app/process

parseProperties

private static boolean parseProperties(java.util.Properties props)
Parses the passed in Properties and pulls out all the name/value pairs and assigns them to the class vars as needed.

Parameters:
props - the Properties to parse
Returns:
true if the method was able to successfully assign all class vars

loadAutoAppPropertiesFile

protected static java.util.Properties loadAutoAppPropertiesFile()
Loads the AutoDownload app information from the properties file so this wrapped app can execute. The properties file is encased in the root dir of this apps jar file.

Returns:
the parsed Properties contained in the file specified by the passed in appPropertyFilename_, null if unable to get the contained Properties

loadPropertiesFile

protected static java.util.Properties loadPropertiesFile(java.lang.String propFilename)
Loads the passed Properties file and returns a Properties object.

Parameters:
propFilename - the filename for the Properties file to parse
Returns:
the parsed Properties contained in the file specified by the passed in propFilename, null if unable to get the contained Properties