gov.nasa.worldwind.cache

Interface FileStore

All Superinterfaces:

AVList, java.util.EventListener, MessageListener, java.beans.PropertyChangeListener, WWObject

All Known Implementing Classes:

AbstractFileStore, BasicDataFileStore

public interface FileStore
extends WWObject

Method Summary

Modifier and Type	Method and Description
void	addLocation(int index, java.lang.String newPath, boolean isInstall) Adds a location to search when files are requested from the file store and specifies its location in the search order.
void	addLocation(java.lang.String newPath, boolean isInstall) Adds a location to search when files are requested from the file store.
boolean	containsFile(java.lang.String fileName) Indicates whether the file store contains a specified file.
java.net.URL	findFile(java.lang.String fileName, boolean checkClassPath) Searches the file store for a specified file and returns a reference to it if it is.
java.lang.String	getContentType(java.lang.String address) Returns the content type of a cached file.
long	getExpirationTime(java.lang.String address) Returns the expiration time of a cached file.
java.util.List<? extends java.io.File>	getLocations() Returns the locations that the file store will look for files.
java.io.File	getWriteLocation() Returns the location that additions to the file store are placed.
boolean	isInstallLocation(java.lang.String path) Indicates whether a specified location is considered an installed-data location and therefore not subject to automatic removal of its contents.
java.lang.String[]	listAllFileNames(java.lang.String pathName, FileStoreFilter filter) Returns an array of strings naming the files discovered under a specified file store path name.
java.lang.String[]	listFileNames(java.lang.String pathName, FileStoreFilter filter) Returns an array of strings naming the files discovered directly under a specified file store path name.
java.lang.String[]	listTopFileNames(java.lang.String pathName, FileStoreFilter filter) Returns an array of strings naming the files discovered under a specified file store path name.
java.io.File	newFile(java.lang.String fileName) Creates a new, empty file in the file store.
void	removeFile(java.lang.String address) Remove an entry from the file store.
void	removeFile(java.net.URL url) Removes a file from the file store using the URL to the cached file.
void	removeLocation(java.lang.String path) Remove a specified read location from the file store.
java.net.URL	requestFile(java.lang.String address) Requests a file.
java.net.URL	requestFile(java.lang.String address, boolean cacheRemoteFile) Requests a file and specifies whether to store retrieved files in the cache or in a temporary location.

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

Method Detail

addLocation

void addLocation(int index,
                 java.lang.String newPath,
                 boolean isInstall)

Adds a location to search when files are requested from the file store and specifies its location in the search order.

Parameters:

index - the location in the search list at which to add the new location.

newPath - the location to add.

isInstall - indicates whether the location is an installed-data location and therefore not subject to automatic removal of its contents.

Throws:

java.lang.IllegalArgumentException - if the specified path is null or empty or the specified index is less than 0.

addLocation

void addLocation(java.lang.String newPath,
                 boolean isInstall)

Adds a location to search when files are requested from the file store.

Parameters:

newPath - the location to add. If the location already exists in the list of read locations its entry is removed and a new entry is added to the end of the search list.

isInstall - indicates whether the location is an "installed data" location and therefore not subject to automatic removal of its contents.

Throws:

java.lang.IllegalArgumentException - if the specified path is null or empty.

containsFile

boolean containsFile(java.lang.String fileName)

Indicates whether the file store contains a specified file.

Parameters:

fileName - the file in question.

Returns:

true if the file store contains the file, false if the file store does not contain the file or the specified path is null.

findFile

java.net.URL findFile(java.lang.String fileName,
                      boolean checkClassPath)

Searches the file store for a specified file and returns a reference to it if it is.

Parameters:

fileName - the file to search for, identified by a path relative to the root of the file store.

checkClassPath - if true, the current classpath is first searched for the file, otherwise the classpath is not searched.

Returns:

a URL addressing the file if it is found.

Throws:

java.lang.IllegalArgumentException - if the specified path is null.

getContentType

java.lang.String getContentType(java.lang.String address)

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

long getExpirationTime(java.lang.String address)

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.

getLocations

java.util.List<? extends java.io.File> getLocations()

Returns the locations that the file store will look for files.

Returns:

the list of locations the file store will search when a file is requested.

getWriteLocation

java.io.File getWriteLocation()

Returns the location that additions to the file store are placed.

Returns:

the location at which new entries are placed.

isInstallLocation

boolean isInstallLocation(java.lang.String path)

Indicates whether a specified location is considered an installed-data location and therefore not subject to automatic removal of its contents.

Parameters:

path - the path in question.

Returns:

true if the location is an installed-data location, otherwise false.

Throws:

java.lang.IllegalArgumentException - if the specified path is null or empty.

listAllFileNames

java.lang.String[] listAllFileNames(java.lang.String pathName,
                                    FileStoreFilter filter)

Returns an array of strings naming the files discovered under a specified file store path name. If the path name is null, the entire file store will be searched. Otherwise the file store is recursively searched under the specified path name for files accepted by the specified filter, until the entire path tree is exhausted. This returns null if the path does not exist in the store. Returned names are relative pointers to a file in the store; they are not necessarily a file system path.

Parameters:

pathName - relative path in the file store to search, or null to search the entire file store.

filter - a file filter.

Returns:

an array of file store names. Returns null if the path does not exist in the file store.

Throws:

java.lang.IllegalArgumentException - if the filter is null.

listFileNames

java.lang.String[] listFileNames(java.lang.String pathName,
                                 FileStoreFilter filter)

Returns an array of strings naming the files discovered directly under a specified file store path name. If the path name is null, files under the store root are searched. This returns null if the path does not exist in the store. Returned names are relative pointers to a file in the store; they are not necessarily a file system path.

Parameters:

pathName - relative path in the file store to search, or null to search the entire file store.

filter - a file filter.

Returns:

an array of file store names. Returns null if the path does not exist in the file store.

Throws:

java.lang.IllegalArgumentException - if the filter is null.

listTopFileNames

java.lang.String[] listTopFileNames(java.lang.String pathName,
                                    FileStoreFilter filter)

Returns an array of strings naming the files discovered under a specified file store path name. If the path name is null, the entire file store will be searched. Otherwise the file store is recursively searched under each branch of the the specified path name until a matching file is found, or that branch is exhausted. Unlike listAllFileNames(String, FileStoreFilter), This has the effect of locating the top file name under each branch. This returns null if the path does not exist in the store. Returned names are relative pointers to a file in the store; they are not necessarily a file system path.

Parameters:

pathName - relative path in the file store to search, or null to search the entire file store.

filter - a file filter.

Returns:

an array of file store names. Returns null if the path does not exist in the file store.

Throws:

java.lang.IllegalArgumentException - if the filter is null.

newFile

java.io.File newFile(java.lang.String fileName)

Creates a new, empty file in the file store.

If the file store has no write location, the file is not created and null is returned.

Parameters:

fileName - the name of the file to create.

Returns:

a reference to the newly created file.

Throws:

java.lang.IllegalArgumentException - if the specified path is null.

removeFile

void removeFile(java.lang.String address)

Remove an entry from the file store. This method removes files that were added to the file store by 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 requestFile(String).

removeFile

void removeFile(java.net.URL url)

Removes a file from the file store using the URL to the cached file.

Parameters:

url - a URL, as returned by findFile(String, boolean) identifying the file.

Throws:

java.lang.IllegalArgumentException - if the specified URL is null.

removeLocation

void removeLocation(java.lang.String path)

Remove a specified read location from the file store. The current write location cannot be removed.

Parameters:

path - the read location to remove.

Throws:

java.lang.IllegalArgumentException - if the specified path is null or identifies the current write location.

requestFile

java.net.URL requestFile(java.lang.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 WorldWind 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.

Throws:

java.lang.IllegalArgumentException - if the address is null.

requestFile

java.net.URL requestFile(java.lang.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 WorldWind 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 WorldWind 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 WorldWind 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 WorldWind 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.

Throws:

java.lang.IllegalArgumentException - if the address is null.