com.threerings.getdown.data

Class Application

java.lang.Object

com.threerings.getdown.data.Application

public class Application
extends Object

Parses and provide access to the information contained in the getdown.txt configuration file.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Application.AuxGroup Contains metadata for an auxiliary resource group.
static interface	Application.StatusDisplay Used by verifyMetadata(com.threerings.getdown.data.Application.StatusDisplay) to communicate status in circumstances where it needs to take network actions.
static class	Application.UpdateInterface Used to communicate information about the UI displayed when updating the application.

Field Summary

Fields

Modifier and Type	Field and Description
static String	CONFIG_FILE The name of our configuration file.
static String	PROP_PASSTHROUGH_PREFIX System properties that are prefixed with this string will be passed through to our application (minus this prefix).
static String	SIGNATURE_SUFFIX Suffix used for control file signatures.
static String	VERSION_FILE The name of our target version file.

Constructor Summary

Constructors

Constructor and Description
Application(File appdir, String appid) Creates an application instance with no signers.
Application(File appdir, String appid, List<Certificate> signers, String[] jvmargs, String[] appargs) Creates an application instance which records the location of the getdown.txt configuration file from the supplied application directory.

Method Summary

Modifier and Type	Method and Description
boolean	allowOffline() Returns true if the app should attempt to run even if we have no Internet connection.
void	attemptRecovery(Application.StatusDisplay status) Attempts to redownload the getdown.txt file based on information parsed from a previous call to init(boolean).
void	clearValidationMarkers() Clears all validation marker files.
Process	createProcess(boolean optimum) Invokes the process associated with this application definition.
List<Resource>	getActiveCodeResources() Returns all main code resources and all code resources from active auxiliary resource groups.
List<Resource>	getActiveResources() Returns all non-code resources and all resources from active auxiliary resource groups.
List<Resource>	getAllActiveResources() Returns a list of all the active Resource objects used by this application (code and non-code).
Application.AuxGroup	getAuxGroup(String name) Returns the auxiliary resource group with the specified name, or null.
Iterable<Application.AuxGroup>	getAuxGroups() Returns the set of all auxiliary resource groups defined by the application.
List<Resource>	getCodeResources() Returns a list of the code Resource objects used by this application.
Resource	getConfigResource() Returns a resource that refers to the application configuration file itself.
Resource	getFullResource() Returns a resource that can be used to download an archive containing all files belonging to the application.
Resource	getJavaVMResource() Returns a resource for a zip file containing a Java VM that can be downloaded to use in place of the installed VM (in the case where the VM that launched Getdown does not meet the application's version requirements) or null if no VM is available for this platform.
File	getLocalPath(String path) Returns the local path to the specified resource.
Resource	getPatchResource(String auxgroup) Returns a resource that can be used to download a patch file that will bring this application from its current version to the target version.
URL	getRemoteURL(String path) Returns a URL from which the specified path can be fetched.
List<Resource>	getResources() Returns a list of the non-code Resource objects used by this application.
String	getTrackingCookieName() Returns the name of our tracking cookie or null if it was not set.
String	getTrackingCookieProperty() Returns the name of our tracking cookie system property or null if it was not set.
URL	getTrackingProgressURL(int percent) Returns the URL to request to report that we have reached the specified percentage of our initial download.
URL	getTrackingURL(String event) Returns the URL to use to report an initial download event.
long	getVersion() Returns the version number for the application.
boolean	hasOptimumJvmArgs() Checks whether the app has a set of "optimum" JVM args that we wish to try first, detecting whether the launch is successful and, if necessary, trying again without the optimum arguments.
boolean	haveValidJavaVersion() Returns true if we either have no version requirement, are running in a JVM that meets our version requirements or have what appears to be a version of the JVM that meets our requirements.
Application.UpdateInterface	init(boolean checkPlatform) Instructs the application to parse its getdown.txt configuration and prepare itself for operation.
static List<Integer>	intsToList(int[] values) Make an immutable List from the specified int array.
void	invokeDirect(JApplet applet) Runs this application directly in the current VM.
boolean	isAuxGroupActive(String auxgroup) Returns true if the specified auxgroup has been "activated", false if not.
boolean	lockForUpdates()
static Color	parseColor(String hexValue) Parses the given hex color value (e.g.
static Rectangle	parseRect(String name, String value) Takes a comma-separated String of four integers and returns a rectangle using those ints as the its x, y, width, and height.
void	releaseLock() Release gettingdown.lock
void	unpackResources(ProgressObserver obs, Set<Resource> unpacked) Unpacks the resources that require it (we know that they're valid).
void	updateMetadata() Downloads and replaces the getdown.txt and digest.txt files with those for the target version of our application.
boolean	verifyMetadata(Application.StatusDisplay status) Loads the digest.txt file and verifies the contents of both that file and the getdown.text file.
List<Resource>	verifyResources(ProgressObserver obs, int[] alreadyValid, Set<Resource> unpacked) Verifies the code and media resources associated with this application.

Methods inherited from class java.lang.Object

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

Field Detail

CONFIG_FILE

public static final String CONFIG_FILE

The name of our configuration file.

See Also:

Constant Field Values

VERSION_FILE

public static final String VERSION_FILE

The name of our target version file.

See Also:

Constant Field Values

PROP_PASSTHROUGH_PREFIX

public static final String PROP_PASSTHROUGH_PREFIX

System properties that are prefixed with this string will be passed through to our application (minus this prefix).

See Also:

Constant Field Values

SIGNATURE_SUFFIX

public static final String SIGNATURE_SUFFIX

Suffix used for control file signatures.

See Also:

Constant Field Values

Constructor Detail

Application

public Application(File appdir,
                   String appid)

Creates an application instance with no signers.

See Also:

Application(File, String, List, String[], String[])

Application

public Application(File appdir,
                   String appid,
                   List<Certificate> signers,
                   String[] jvmargs,
                   String[] appargs)

Creates an application instance which records the location of the getdown.txt configuration file from the supplied application directory.

Parameters:

appid - usually null but a string identifier if a secondary application is desired to be launched. That application will use appid.class and appid.apparg to configure itself but all other parameters will be the same as the primary application.

signers - a list of possible signers of this application. Used to verify the digest.

jvmargs - additional arguments to pass on to launched jvms.

appargs - additional arguments to pass on to launched application; these will be added after the args in the getdown.txt file.

Method Detail

getConfigResource

public Resource getConfigResource()

Returns a resource that refers to the application configuration file itself.

getCodeResources

public List<Resource> getCodeResources()

Returns a list of the code Resource objects used by this application.

getResources

public List<Resource> getResources()

Returns a list of the non-code Resource objects used by this application.

getAllActiveResources

public List<Resource> getAllActiveResources()

Returns a list of all the active Resource objects used by this application (code and non-code).

getAuxGroup

public Application.AuxGroup getAuxGroup(String name)

Returns the auxiliary resource group with the specified name, or null.

getAuxGroups

public Iterable<Application.AuxGroup> getAuxGroups()

Returns the set of all auxiliary resource groups defined by the application. An auxiliary resource group is a collection of resource files that are not downloaded unless a group token file is present in the application directory.

isAuxGroupActive

public boolean isAuxGroupActive(String auxgroup)

Returns true if the specified auxgroup has been "activated", false if not. Non-activated groups should be ignored, activated groups should be downloaded and patched along with the main resources.

getActiveCodeResources

public List<Resource> getActiveCodeResources()

Returns all main code resources and all code resources from active auxiliary resource groups.

getActiveResources

public List<Resource> getActiveResources()

Returns all non-code resources and all resources from active auxiliary resource groups.

getPatchResource

public Resource getPatchResource(String auxgroup)

Returns a resource that can be used to download a patch file that will bring this application from its current version to the target version.

Parameters:

auxgroup - the auxiliary resource group for which a patch resource is desired or null for the main application patch resource.

getJavaVMResource

public Resource getJavaVMResource()

Returns a resource for a zip file containing a Java VM that can be downloaded to use in place of the installed VM (in the case where the VM that launched Getdown does not meet the application's version requirements) or null if no VM is available for this platform.

getFullResource

public Resource getFullResource()

Returns a resource that can be used to download an archive containing all files belonging to the application.

getTrackingURL

public URL getTrackingURL(String event)

Returns the URL to use to report an initial download event. Returns null if no tracking start URL was configured for this application.

Parameters:

event - the event to be reported: start, jvm_start, jvm_complete, complete.

getTrackingProgressURL

public URL getTrackingProgressURL(int percent)

Returns the URL to request to report that we have reached the specified percentage of our initial download. Returns null if no tracking request was configured for the specified percentage.

getTrackingCookieName

public String getTrackingCookieName()

Returns the name of our tracking cookie or null if it was not set.

getTrackingCookieProperty

public String getTrackingCookieProperty()

Returns the name of our tracking cookie system property or null if it was not set.

init

public Application.UpdateInterface init(boolean checkPlatform)
                                 throws IOException

Instructs the application to parse its getdown.txt configuration and prepare itself for operation. The application base URL will be parsed first so that if there are errors discovered later, the caller can use the application base to download a new getdown.txt file and try again.

Returns:

a configured UpdateInterface instance that will be used to configure the update UI.

Throws:

IOException - thrown if there is an error reading the file or an error encountered during its parsing.

getRemoteURL

public URL getRemoteURL(String path)
                 throws MalformedURLException

Returns a URL from which the specified path can be fetched. Our application base URL is properly versioned and combined with the supplied path.

Throws:

MalformedURLException

getLocalPath

public File getLocalPath(String path)

Returns the local path to the specified resource.

haveValidJavaVersion

public boolean haveValidJavaVersion()

Returns true if we either have no version requirement, are running in a JVM that meets our version requirements or have what appears to be a version of the JVM that meets our requirements.

hasOptimumJvmArgs

public boolean hasOptimumJvmArgs()

Checks whether the app has a set of "optimum" JVM args that we wish to try first, detecting whether the launch is successful and, if necessary, trying again without the optimum arguments.

allowOffline

public boolean allowOffline()

Returns true if the app should attempt to run even if we have no Internet connection.

attemptRecovery

public void attemptRecovery(Application.StatusDisplay status)
                     throws IOException

Attempts to redownload the getdown.txt file based on information parsed from a previous call to init(boolean).

Throws:

IOException

updateMetadata

public void updateMetadata()
                    throws IOException

Downloads and replaces the getdown.txt and digest.txt files with those for the target version of our application.

Throws:

IOException

createProcess

public Process createProcess(boolean optimum)
                      throws IOException

Invokes the process associated with this application definition.

Parameters:

optimum - whether or not to include the set of optimum arguments (as opposed to falling back).

Throws:

IOException

invokeDirect

public void invokeDirect(JApplet applet)

Runs this application directly in the current VM.

verifyMetadata

public boolean verifyMetadata(Application.StatusDisplay status)
                       throws IOException

Loads the digest.txt file and verifies the contents of both that file and the getdown.text file. Then it loads the version.txt and decides whether or not the application needs to be updated or whether we can proceed to verification and execution.

Returns:

true if the application needs to be updated, false if it is up to date and can be verified and executed.

Throws:

IOException - thrown if we encounter an unrecoverable error while verifying the metadata.

verifyResources

public List<Resource> verifyResources(ProgressObserver obs,
                                      int[] alreadyValid,
                                      Set<Resource> unpacked)
                               throws InterruptedException

Verifies the code and media resources associated with this application. A list of resources that do not exist or fail the verification process will be returned. If all resources are ready to go, null will be returned and the application is considered ready to run.

Parameters:

alreadyValid - if non-null a 1 element array that will have the number of "already validated" resources filled in.

unpacked - a set to populate with unpacked resources.

Throws:

InterruptedException

unpackResources

public void unpackResources(ProgressObserver obs,
                            Set<Resource> unpacked)
                     throws InterruptedException

Unpacks the resources that require it (we know that they're valid).

Parameters:

unpacked - a set of resources to skip because they're already unpacked.

Throws:

InterruptedException

clearValidationMarkers

public void clearValidationMarkers()

Clears all validation marker files.

getVersion

public long getVersion()

Returns the version number for the application. Should only be called after successful return of verifyMetadata.

lockForUpdates

public boolean lockForUpdates()

Returns:

true if gettingdown.lock was unlocked, already locked by this application or if we're not locking at all.

releaseLock

public void releaseLock()

Release gettingdown.lock

intsToList

public static List<Integer> intsToList(int[] values)

Make an immutable List from the specified int array.

parseRect

public static Rectangle parseRect(String name,
                                  String value)

Takes a comma-separated String of four integers and returns a rectangle using those ints as the its x, y, width, and height.

parseColor

public static Color parseColor(String hexValue)

Parses the given hex color value (e.g. FFFFF) and returns a Color object with that value. If the given value is null of not a valid hexadecimal number, this will return null.