gov.nasa.worldwind.cache
Class BasicDataFileStore

java.lang.Object
  gov.nasa.worldwind.avlist.AVListImpl
      gov.nasa.worldwind.WWObjectImpl
          gov.nasa.worldwind.cache.AbstractFileStore
              gov.nasa.worldwind.cache.BasicDataFileStore

All Implemented Interfaces:

AVList, FileStore, MessageListener, WWObject, PropertyChangeListener, EventListener

public class BasicDataFileStore
extends AbstractFileStore

Basic implementation of FileStore.

Nested Class Summary

protected static class	BasicDataFileStore.DBEntry Holds information for entries in the cache database.
protected class	BasicDataFileStore.PostProcessor

Nested classes/interfaces inherited from class gov.nasa.worldwind.cache.AbstractFileStore

AbstractFileStore.StoreLocation

Field Summary

protected AbsentResourceList	absentResources Absent-resource list to keep track of resources that were requested by requestFile but failed.
protected List<String>	cacheContentTypes The list of content types used to determine an unknown file format in requestFile.
protected BasicMemoryCache	db The map of cached entries.
protected static List<String>	DEFAULT_CACHE_CONTENT_TYPES The default content types used to determine an unknown file format in requestFile.
protected static long	TIMEOUT The number of milliseconds to wait before a retrieval request for the same file can be reissued.

Fields inherited from class gov.nasa.worldwind.cache.AbstractFileStore

readLocations, writeLocation

Constructor Summary

BasicDataFileStore()
Create an instance.

BasicDataFileStore(File directoryPath)
Create an instance to manage a specified directory.

Method Summary

protected AbsentResourceList	getAbsentResourceList() Returns this file store's absent-resource list.
protected List<String>	getCacheContentTypes() Returns this file store's list of content types.
String	getContentType(String address) Returns the content type of a cached file.
long	getExpirationTime(String address) Returns the expiration time of a cached file.
protected int	getJarLength(URL jarUrl) Returns the length of the resource referred to by a jar URL.
protected URL	getLocalFileUrl(String address, URL retrievalUrl, boolean searchLocalCache) Returns a file from the cache, the local file system or the classpath if the file exists.
protected void	initialize(InputStream xmlConfigStream)
protected String	makeCachePath(URL url, String contentType) Makes a path to the file in the cache from the file's URL and content type.
protected String	makeGenericURLCachePath(URL url, String contentType) Makes a path to the file in the cache from the file's generic URL and content type.
protected String	makeJarURLCachePath(URL jarURL, String contentType) Makes a path to the file in the cache from the file's JAR URL and content type.
protected void	makeLocal(String address, URL url, boolean saveInLocalCache) Retrieves a specified file and either adds it to the cache or saves it in a temporary file, depending on the value of saveInLocalCache.
protected String	makeSuffix(String path, String contentType) Determines an appropriate suffix for a cached file.
protected File	makeTempFile(URL url, String contentType) Creates a temp file to hold the contents associated with a specified URL.
void	removeFile(String address) Remove an entry from the file store.
protected String	removePrivateQueryParameters(String queryString) Removes any private parameters from the query string to ensure that those parameters are not written to the file store as part of the cache name.
URL	requestFile(String address) Requests a file.
URL	requestFile(String address, boolean cacheRemoteFile) Requests a file and specifies whether to store retrieved files in the cache or in a temporary location.
protected void	updateEntry(String address, URL localFileUrl, long expiration) Updates a cache entry with information available once the file is retrieved.

Methods inherited from class gov.nasa.worldwind.cache.AbstractFileStore

addLocation, addLocation, buildLocationPath, buildReadPaths, buildWritePaths, containsFile, determineAllUserLocation, determineSingleUserLocation, doListFileNames, doListFileNames, findFile, getLocations, getUserHomeDir, getWriteLocation, isInstallLocation, listAllFileNames, listFile, listFileName, listFileNames, listTopFileNames, makeAbsoluteFile, makeAbsolutePath, markFileUsed, newFile, normalizeFileStoreName, propertyToPath, removeFile, removeLocation, storeLocationFor, storePathForFile

Methods inherited from class gov.nasa.worldwind.WWObjectImpl

onMessage, propertyChange

Methods inherited from class gov.nasa.worldwind.avlist.AVListImpl

addPropertyChangeListener, addPropertyChangeListener, clearList, copy, firePropertyChange, firePropertyChange, getBooleanValue, getBooleanValue, getChangeSupport, getDoubleValue, getDoubleValue, getEntries, getIntegerValue, getIntegerValue, getLongValue, getLongValue, getRestorableStateForAVPair, getStringValue, getStringValue, getStringValue, getValue, getValues, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue, setValues

Methods inherited from class java.lang.Object

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

Methods inherited from interface gov.nasa.worldwind.avlist.AVList

addPropertyChangeListener, addPropertyChangeListener, clearList, copy, firePropertyChange, firePropertyChange, getEntries, getStringValue, getValue, getValues, hasKey, removeKey, removePropertyChangeListener, removePropertyChangeListener, setValue, setValues

Methods inherited from interface java.beans.PropertyChangeListener

propertyChange

Methods inherited from interface gov.nasa.worldwind.event.MessageListener

onMessage

Field Detail

absentResources

protected AbsentResourceList absentResources

Absent-resource list to keep track of resources that were requested by requestFile but failed. The default list holds a maximum of 2000 entries, allows 3 attempts separated by 500 milliseconds before marking a resource semi-permanently absent, and allows additional attempts after 60 seconds. The getAbsentResourceList() method may be overridden by subclasses if they wish to provide an alternatively configured absent-resource list.

cacheContentTypes

protected List<String> cacheContentTypes

The list of content types used to determine an unknown file format in requestFile. If a URL is requested that does not have a format suffix, requestFile appends a suffix appropriate for the content type returned by the server. Subsequent calls to requestFile use the content types in this list to find the content type matching the cached file.

This is initialized to the following list of default content types typically used in World Wind applications:

• application/vnd.google-earth.kml+xml
• application/vnd.google-earth.kmz
• model/collada+xml
• image/dds
• image/gif
• image/jpeg
• image/jpg
• image/png

This list may be overridden by specifying a comma-delimited list of content types in the World Wind configuration parameter gov.nasa.worldwind.avkey.CacheContentTypes.

db

protected BasicMemoryCache db

The map of cached entries.

DEFAULT_CACHE_CONTENT_TYPES

protected static final List<String> DEFAULT_CACHE_CONTENT_TYPES

The default content types used to determine an unknown file format in requestFile.

TIMEOUT

protected static final long TIMEOUT

The number of milliseconds to wait before a retrieval request for the same file can be reissued.

See Also:

Constant Field Values

Constructor Detail

BasicDataFileStore

public BasicDataFileStore()

Create an instance.

Throws:

IllegalStateException - if the configuration file name cannot be determined from Configuration or the configuration file cannot be found.

BasicDataFileStore

public BasicDataFileStore(File directoryPath)

Create an instance to manage a specified directory.

Parameters:

directoryPath - the directory to manage as a file store.

Method Detail

getAbsentResourceList

protected AbsentResourceList getAbsentResourceList()

Returns this file store's absent-resource list.

Returns:

the file store's absent-resource list.

getCacheContentTypes

protected List<String> getCacheContentTypes()

Returns this file store's list of content types.

Returns:

the file store's list of content types.

getContentType

public String getContentType(String address)

Description copied from interface: FileStore

Returns the content type of a cached file.

Parameters:

address - the file's address. If null, null is returned.

Returns:

the mime type describing the cached file's contents. Null is returned if the specified address is null.

getExpirationTime

public long getExpirationTime(String address)

Description copied from interface: FileStore

Returns the expiration time of a cached file.

Parameters:

address - the file's address. If null, zero is returned.

Returns:

The expiration time of the file, in milliseconds since the Epoch (January 1, 1970, 00:00:00 GMT). Zero indicates that there is no expiration time.

getJarLength

protected int getJarLength(URL jarUrl)

Returns the length of the resource referred to by a jar URL. Can be used to test whether the resource exists.

Note: This method causes the URL to open a connection and retrieve content length.

Parameters:

jarUrl - the jar URL.

Returns:

the jar file's content length, or -1 if a connection to the URL can't be formed or queried.

getLocalFileUrl

protected URL getLocalFileUrl(String address,
                              URL retrievalUrl,
                              boolean searchLocalCache)

Returns a file from the cache, the local file system or the classpath if the file exists. The specified address may be a jar URL. See JarURLConnection for a description of jar URLs. If searchLocalCache is true this looks for the file in the World Wind cache, otherwise this only looks for the file in the local file system and the classpath.

Parameters:

address - the name used to identify the cached file.

retrievalUrl - the URL to obtain the file if it is not in the cache. Used only to determine a location to search in the local cache. May be null.

searchLocalCache - true to look for the file in the World Wind cache, otherwise false.

Returns:

the requested file if it exists, otherwise null.

Throws:

IllegalArgumentException - if the specified address is null.

initialize

protected void initialize(InputStream xmlConfigStream)

Overrides:

initialize in class AbstractFileStore

makeCachePath

protected String makeCachePath(URL url,
                               String contentType)

Makes a path to the file in the cache from the file's URL and content type.

Parameters:

url - the URL to obtain the file.

contentType - the mime type of the file's contents.

Returns:

a path name.

makeGenericURLCachePath

protected String makeGenericURLCachePath(URL url,
                                         String contentType)

Makes a path to the file in the cache from the file's generic URL and content type. If the URL has a non-empty query string, then this returns a path name formatted as follows:

host/hashCode/path_query.suffix

Otherwise, this returns a path name formatted as follows:

host/hashCode/path.suffix

Where host is the name of the host machine, hashCode is a four digit hash code computed from the string "path" or "path_query" (if the URL has a query string), path is the URL's path part, query is the URL's query string, and suffix is either the path's suffix or a suffix created from the specified content type. The hashCode folder is used to limit the number of files that appear beneath the host folder. This is necessary to avoiding the operating system's maximum file limit should a large number of files be requested from the same host. If two URLs have the same hash code, then both URLs are stored under the same hashCode folder in the cache and are differentiated by their path and query parts.

This removes any private parameters from the query string to ensure that those parameters are not written to the file store as part of the cache name. For example, the "CONNECTID" query parameter typically encodes a user's unique connection id, and must not be shared. Writing this parameter to the cache would expose that parameter to anyone using the same machine. If the query string is empty after removing any private parameters, it is ignored and only the path part of the URL is used as the filename.

Parameters:

url - the URL to obtain the file.

contentType - the mime type of the file's contents.

Returns:

a path name.

makeJarURLCachePath

protected String makeJarURLCachePath(URL jarURL,
                                     String contentType)

Makes a path to the file in the cache from the file's JAR URL and content type. This returns a path name formatted as follows:

host/path.suffix

Where host is the path to the JAR file, path is the file's path within the JAR archive, and suffix is either the path's suffix or a suffix created from the specified content type.

Parameters:

jarURL - the URL to obtain the file. This URL is assumed to have the "jar" protocol.

contentType - the mime type of the file's contents.

Returns:

a path name.

makeLocal

protected void makeLocal(String address,
                         URL url,
                         boolean saveInLocalCache)

Retrieves a specified file and either adds it to the cache or saves it in a temporary file, depending on the value of saveInLocalCache.

Parameters:

address - the name used to identify the cached file.

url - the URL to obtain the file.

saveInLocalCache - true to add the file to the cache, or false to save it in a temporary location.

makeSuffix

protected String makeSuffix(String path,
                            String contentType)

Determines an appropriate suffix for a cached file. If the specified path already has a suffix that matches the specified content type, then this method returns null. Otherwise the method determines and returns a suffix for the specified content type.

Parameters:

path - the path whose suffix is to be validated if it exists.

contentType - the mime type of the data associated with the path.

Returns:

a suffix appropriate to the content type, or null if the specified path already has an appropriate suffix.

makeTempFile

protected File makeTempFile(URL url,
                            String contentType)

Creates a temp file to hold the contents associated with a specified URL. Since the file store intentionally does not persist a mapping of retrieved URLs to temp files, this deletes the returned temp file when the current Java Virtual Machine terminates.

Parameters:

url - the URL to be associated with the temp file. Used only to determine an appropriate suffix.

contentType - the mime type of the file contents. Used to determine the file's suffix.

Returns:

a temporary file, or null if a file could not be created.

removeFile

public void removeFile(String address)

Remove an entry from the file store. This method removes files that were added to the file store by FileStore.requestFile(String). The address passed to this method must be the same as the address string that was passed to requestFile when the file was added.

Parameters:

address - file address of the entry to remove. This must be the same string as was passed to FileStore.requestFile(String).

removePrivateQueryParameters

protected String removePrivateQueryParameters(String queryString)

Removes any private parameters from the query string to ensure that those parameters are not written to the file store as part of the cache name. For example, the "CONNECTID" query parameter typically encodes a user's unique connection id, and must not be shared. Writing this parameter to the cache would expose that parameter to anyone using the same machine.

This removes the key, the value, and any trailing parameter delimiter of all private parameters in the specified query string. Recognized private query parameters are as follows:

• CONNECTID

Parameters:

queryString - the query string to examine.

Returns:

a new string with the private query parameters removed. This string is empty if the query string is empty, or if the query string contains only private parameters.

requestFile

public URL requestFile(String address)

Requests a file. If the file exists locally, including as a resource on the classpath, this returns a URL to the file. Otherwise if the specified address is a URL to a remote location, this initiates a request for the file and returns null. When the request succeeds the file is stored in the local World Wind cache and subsequent invocations of this method return a URL to the retrieved file.

Parameters:

address - the file address: either a local file, a URL, or a path relative to the root of the file store.

Returns:

the file's URL if it exists locally or is a remote file that has been retrieved, otherwise null.

requestFile

public URL requestFile(String address,
                       boolean cacheRemoteFile)

Requests a file and specifies whether to store retrieved files in the cache or in a temporary location. If the file exists locally, including as a resource on the classpath, this returns a URL to the file. Otherwise if the specified address is a URL to a remote location, this initiates a request for the file and returns null. When the request succeeds the file is stored either in the local World Wind cache or in a temporary location and subsequent invocations of this method return a URL to the retrieved file.

The cacheRemoteFile parameter specifies whether to store a retrieved remote file in the World Wind cache or in a temporary location. This parameter has no effect if the file exists locally. The temporary location for a retrieved file does not persist between runtime sessions, and subsequent invocations of this method may not return the same temporary location.

If a remote file is requested multiple times with different values for cacheRemoteFile, it is undefined whether the retrieved file is stored in the World Wind cache or in a temporary location.

Parameters:

address - the file address: either a local file, a URL, or a path relative to the root of the file store.

cacheRemoteFile - true to store remote files in the World Wind cache, or false to store remote files in a temporary location. Has no effect if the address is a local file.

Returns:

the file's URL if it exists locally or is a remote file that has been retrieved, otherwise null.

updateEntry

protected void updateEntry(String address,
                           URL localFileUrl,
                           long expiration)

Updates a cache entry with information available once the file is retrieved.

Parameters:

address - the name used to identify the file in the cache.

localFileUrl - the path to the local copy of the file.

expiration - time (in milliseconds since the Epoch) at which this entry expires, or zero to indicate that there is no expiration time.