ecologylab.io
Class Assets

java.lang.Object
  ecologylab.generic.Debug
      ecologylab.io.Assets

All Implemented Interfaces:

ApplicationProperties, ApplicationPropertyNames

public class Assets
extends Debug
implements ApplicationProperties

Used to manage cachable assets.

This class must not be called until codeBase is properly set!

Here's how it works: (1) There is a file called assets.xml. It lives only in applicationDataDir(), the cache root. There is *no* version of this file in /config/preferences, the assets root. This file stores the *current* cached version # of each asset. (2) The version of each Asset is a constant, which lives *in the code*. It is passed to Assets.downloadZip(). (3) If there is no local versions of assets.xml (first time ap is run), or if any version turns out to be stale, the assets.xml file will need to be written to the cache root. The application *must* call updateAssetsXml() to do this, after it is finished reading all Assets. This method will know if writing the file is needed or not.

Author:

blake, andruid

Field Summary

static float	IGNORE_VERSION
static java.lang.String	INTERFACE current known assets (although arbitrary ones can exist)
static java.lang.String	PREFERENCES
static java.lang.String	SEMANTICS

Fields inherited from interface ecologylab.appframework.ApplicationProperties

USE_ASSETS_CACHE

Fields inherited from interface ecologylab.appframework.ApplicationPropertyNames

CODEBASE, FRAME, GO_PREFIX, PREFERENCES_SET, PREFERENCES_SET_ASSET

Method Summary

static ParsedURL	assetsRoot() Get the source URL root of the tree of assets for this application.
static java.io.File	cacheRoot() Get the root file path for caching.
static boolean	downloadInterfaceZip(java.lang.String assetRelativePath, StatusReporter status, boolean forceDownload) Download an interface assets zip file from the interfaceAssetsRoot.
static boolean	downloadInterfaceZip(java.lang.String assetRelativePath, StatusReporter status, boolean forceDownload, float version)
static void	downloadPreferencesZip(java.lang.String assetRelativePath, StatusReporter status, boolean forceDownload)
static void	downloadPreferencesZip(java.lang.String assetRelativePath, StatusReporter status, boolean forceDownload, float version)
static void	downloadSemanticsZip(java.lang.String assetRelativePath, StatusReporter status, boolean forceDownload) Download an semantics assets zip file from the semanticsAssetsRoot.
static void	downloadSemanticsZip(java.lang.String assetRelativePath, StatusReporter status, boolean forceDownload, float version)
static void	downloadXML(ParsedURL sourceXML, java.io.File targetDir, StatusReporter status) Download an XML file from a source to a target location with minimal effort, unless the XML file already exists at the target location, in which case, do nothing.
static void	downloadXML(java.lang.String sourcePath, java.lang.String targetPath, StatusReporter status) Download XML from the sourcePath, within the assetsRoot (the application's config dir), to the target path within the applicationDir.
static void	downloadZip(ParsedURL sourceZip, java.io.File targetFile, boolean forceDownload, float version)
static void	downloadZip(ParsedURL sourceZip, java.io.File targetDir, StatusReporter status, boolean forceDownload, float version) Download and uncompress a zip file from a source to a target location with minimal effort, unless the zip file already exists at the target location, in which case, do nothing.
static void	downloadZip(java.lang.String assetRelativePath, boolean forceDownload, float version) Download the assets zip file from the assetsRoot.
static void	downloadZip(java.lang.String assetRelativePath, StatusReporter status, boolean forceDownload, float version) Download the assets zip file from the assetsRoot.
static java.io.File	getAndPerhapsCreateAsset(java.lang.String relativePath) Same as getAsset(String), but creates the Asset location if it doesn't exist
static java.io.File	getAndPerhapsCreateAsset(java.lang.String relativePath, java.lang.String additionalContext) Same as getAndPerhapsCreateAsset(String, String), but creates the Asset location if it doesn't exist
static java.io.File	getAsset(java.lang.String relativePath) Given a relative path, return a file reference to this path from the cache root.
static java.io.File	getAsset(java.lang.String relativePath, java.lang.String additionalContext) Same as getAsset(String), but allows additional relative file/directory to be specified against the relativePath
static java.io.File	getCachedInterfaceFile(java.lang.String assetRelativePath) Use the interfaceCacheRoot to produce a File object using the specified relative path.
static java.lang.String	getCacheFilename(ParsedURL location, java.io.File directory, java.lang.String additional, java.lang.String separator, java.lang.String extension) Derive a non-duplicate cache filename given a ParsedURL location
static java.io.File	getInterfaceFile(java.lang.String assetRelativePath)
static java.io.File	getPreferencesFile(java.lang.String assetRelativePath)
static java.io.File	getSemanticsFile(java.lang.String assetRelativePath)
static boolean	localVersionIsUpToDate(java.lang.String id, float requiredVersion) Determines if a file should be downloaded again, based upon it's file version.
static void	setAssetsRoot(ParsedURL assetsRoot) Set the source URL root of the tree of assets for this application.
static void	setCacheRoot(java.io.File cacheRoot) Sets the root file path for caching.
static void	updateAssetsXml(java.lang.String sourceSpot) When necessary, re-write the local (and only) assets.xml file.

Methods inherited from class ecologylab.generic.Debug

classSimpleName, closeLoggingFile, debug, debug, debug, debug, debugA, debugA, debugA, debugI, debugI, debugI, error, error, getClassName, getClassName, getInteractive, getPackageName, getPackageName, getPackageName, initialize, level, level, level, logToFile, print, print, println, println, println, println, println, println, printlnA, printlnA, printlnA, printlnI, printlnI, printlnI, printlnI, setLoggingFile, show, show, superString, toggleInteractive, toString, toString, warning, warning, weird, weird

Methods inherited from class java.lang.Object

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

Field Detail

INTERFACE

public static final java.lang.String INTERFACE

current known assets (although arbitrary ones can exist)

See Also:

Constant Field Values

SEMANTICS

public static final java.lang.String SEMANTICS

See Also:

Constant Field Values

PREFERENCES

public static final java.lang.String PREFERENCES

See Also:

Constant Field Values

IGNORE_VERSION

public static final float IGNORE_VERSION

See Also:

Constant Field Values

Method Detail

getAsset

public static java.io.File getAsset(java.lang.String relativePath)

Given a relative path, return a file reference to this path from the cache root.

Parameters:

relativePath - A string representing the relative file path.

Returns:

A file reference to the requested path

getAsset

public static java.io.File getAsset(java.lang.String relativePath,
                                    java.lang.String additionalContext)

Same as getAsset(String), but allows additional relative file/directory to be specified against the relativePath

Parameters:

relativePath - A string representing the relative file path

additionalContext - A string representing an additional relative path. This path is relative to the relativePath parameter (rather than the cache root).

Returns:

A file reference to the requested path

getAndPerhapsCreateAsset

public static java.io.File getAndPerhapsCreateAsset(java.lang.String relativePath)

Same as getAsset(String), but creates the Asset location if it doesn't exist

Parameters:

relativePath - A string representing the relative file path.

Returns:

A file reference tot he requested path

getAndPerhapsCreateAsset

public static java.io.File getAndPerhapsCreateAsset(java.lang.String relativePath,
                                                    java.lang.String additionalContext)

Same as getAndPerhapsCreateAsset(String, String), but creates the Asset location if it doesn't exist

Parameters:

relativePath - A string representing the relative file path.

additionalContext - A string representing an additional relative path. This path is relative to the relativePath parameter (rather than the cache root).

Returns:

A file reference to the requested path

See Also:

getAsset(String, String)

getInterfaceFile

public static java.io.File getInterfaceFile(java.lang.String assetRelativePath)

Parameters:

assetRelativePath -

Returns:

getCachedInterfaceFile

public static java.io.File getCachedInterfaceFile(java.lang.String assetRelativePath)

Use the interfaceCacheRoot to produce a File object using the specified relative path.

Parameters:

assetRelativePath -

Returns:

getSemanticsFile

public static java.io.File getSemanticsFile(java.lang.String assetRelativePath)

Parameters:

assetRelativePath -

Returns:

getPreferencesFile

public static java.io.File getPreferencesFile(java.lang.String assetRelativePath)

downloadInterfaceZip

public static boolean downloadInterfaceZip(java.lang.String assetRelativePath,
                                           StatusReporter status,
                                           boolean forceDownload)

Download an interface assets zip file from the interfaceAssetsRoot. Unzip it into the cacheRoot.

Parameters:

assetRelativePath - -- This is the name of the interface. It does not end in .zip!

status - Provide feedback to the user at the bottom of a window, or such.

Returns:

false if the assetRelativePath is null; otherwise true.

downloadInterfaceZip

public static boolean downloadInterfaceZip(java.lang.String assetRelativePath,
                                           StatusReporter status,
                                           boolean forceDownload,
                                           float version)

downloadSemanticsZip

public static void downloadSemanticsZip(java.lang.String assetRelativePath,
                                        StatusReporter status,
                                        boolean forceDownload)

Download an semantics assets zip file from the semanticsAssetsRoot. Unzip it into the cacheRoot.

Parameters:

assetRelativePath -

status - Provide feedback to the user at the bottom of a window, or such.

downloadSemanticsZip

public static void downloadSemanticsZip(java.lang.String assetRelativePath,
                                        StatusReporter status,
                                        boolean forceDownload,
                                        float version)

downloadPreferencesZip

public static void downloadPreferencesZip(java.lang.String assetRelativePath,
                                          StatusReporter status,
                                          boolean forceDownload)

downloadPreferencesZip

public static void downloadPreferencesZip(java.lang.String assetRelativePath,
                                          StatusReporter status,
                                          boolean forceDownload,
                                          float version)

downloadZip

public static void downloadZip(java.lang.String assetRelativePath,
                               StatusReporter status,
                               boolean forceDownload,
                               float version)

Download the assets zip file from the assetsRoot. Unzip it into the cacheRoot.

Parameters:

assetRelativePath -

status - Provide feedback to the user at the bottom of a window, or such.

downloadZip

public static void downloadZip(java.lang.String assetRelativePath,
                               boolean forceDownload,
                               float version)

Download the assets zip file from the assetsRoot. Unzip it into the cacheRoot. Don't bother providing feedback to the user.

Parameters:

assetRelativePath -

downloadZip

public static void downloadZip(ParsedURL sourceZip,
                               java.io.File targetFile,
                               boolean forceDownload,
                               float version)

downloadZip

public static void downloadZip(ParsedURL sourceZip,
                               java.io.File targetDir,
                               StatusReporter status,
                               boolean forceDownload,
                               float version)

Download and uncompress a zip file from a source to a target location with minimal effort, unless the zip file already exists at the target location, in which case, do nothing.

Parameters:

status - The Status object that provides a source of state change visiblity; can be null.

forceDownload -

version -

setAssetsRoot

public static void setAssetsRoot(ParsedURL assetsRoot)

Set the source URL root of the tree of assets for this application. Default is the configDir(), which in turn is the config subdir of codebase. The source location of any asset is specified relative to here.

setCacheRoot

public static void setCacheRoot(java.io.File cacheRoot)

Sets the root file path for caching. Assets are specified relative to this path.

Parameters:

cacheRoot - The root file path for caching assets.

assetsRoot

public static ParsedURL assetsRoot()

Get the source URL root of the tree of assets for this application. Default is the configDir(), which in turn is the config subdir of codebase.

Returns:

ParsedURL referring to the root of the remote place we download assets from.

cacheRoot

public static java.io.File cacheRoot()

Get the root file path for caching. Assets are specified relative to this path.

Returns:

downloadXML

public static void downloadXML(java.lang.String sourcePath,
                               java.lang.String targetPath,
                               StatusReporter status)

Download XML from the sourcePath, within the assetsRoot (the application's config dir), to the target path within the applicationDir.

Parameters:

sourcePath -

targetPath -

status -

downloadXML

public static void downloadXML(ParsedURL sourceXML,
                               java.io.File targetDir,
                               StatusReporter status)

Download an XML file from a source to a target location with minimal effort, unless the XML file already exists at the target location, in which case, do nothing.

Parameters:

status - The Status object that provides a source of state change visiblity; can be null.

sourceXML - The location of the zip file to download and uncompress.

targetDir - The location where the zip file should be uncompressed. This directory structure will be created if it doesn't exist.

localVersionIsUpToDate

public static boolean localVersionIsUpToDate(java.lang.String id,
                                             float requiredVersion)

Determines if a file should be downloaded again, based upon it's file version.

Parameters:

id - the name of the file to check

requiredVersion - the version of that file \

Returns:

false if the local asset is stale and to download true if the local version is fine and we dont need to download

updateAssetsXml

public static void updateAssetsXml(java.lang.String sourceSpot)

When necessary, re-write the local (and only) assets.xml file.

getCacheFilename

public static java.lang.String getCacheFilename(ParsedURL location,
                                                java.io.File directory,
                                                java.lang.String additional,
                                                java.lang.String separator,
                                                java.lang.String extension)

Derive a non-duplicate cache filename given a ParsedURL location

Parameters:

location - The location of the file to be cached.

directory - The directory to cache the file

additional - An additional text to add to the end of the filename, but before the extension

separator - Separator used to divide sections of filename (e.g. "-", ".")

extension - Extension to add to file name if it doesn't already exist

Returns:

A string containing the new filename