Package gov.nasa.worldwind.cache

Class BasicDataFileStore

    • Field Detail

      • 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

      • DEFAULT_CACHE_CONTENT_TYPES

        protected static final java.util.List<java.lang.String> DEFAULT_CACHE_CONTENT_TYPES
        The default content types used to determine an unknown file format in requestFile.

      • 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 java.util.List<java.lang.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 WorldWind 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 WorldWind configuration parameter gov.nasa.worldwind.avkey.CacheContentTypes.

    • Constructor Detail

      • BasicDataFileStore

        public BasicDataFileStore()
        Create an instance.
        Throws:
        java.lang.IllegalStateException - if the configuration file name cannot be determined from Configuration or the configuration file cannot be found.

      • BasicDataFileStore

        public BasicDataFileStore​(java.io.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 java.util.List<java.lang.String> getCacheContentTypes()
        Returns this file store's list of content types.
        Returns:
        the file store's list of content types.

      • getContentType

        public java.lang.String getContentType​(java.lang.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​(java.lang.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.

      • removeFile

        public 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 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).

      • requestFile

        public 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.

      • requestFile

        public 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.

      • getLocalFileUrl

        protected java.net.URL getLocalFileUrl​(java.lang.String address,
                                       java.net.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 WorldWind 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 WorldWind cache, otherwise false.
        Returns:
        the requested file if it exists, otherwise null.
        Throws:
        java.lang.IllegalArgumentException - if the specified address is null.

      • getJarLength

        protected int getJarLength​(java.net.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.

      • makeLocal

        protected void makeLocal​(java.lang.String address,
                         java.net.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.

      • updateEntry

        protected void updateEntry​(java.lang.String address,
                           java.net.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.

      • makeCachePath

        protected java.lang.String makeCachePath​(java.net.URL url,
                                         java.lang.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 java.lang.String makeGenericURLCachePath​(java.net.URL url,
                                                   java.lang.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 java.lang.String makeJarURLCachePath​(java.net.URL jarURL,
                                               java.lang.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.

      • makeTempFile

        protected java.io.File makeTempFile​(java.net.URL url,
                                    java.lang.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.

      • makeSuffix

        protected java.lang.String makeSuffix​(java.lang.String path,
                                      java.lang.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.

      • removePrivateQueryParameters

        protected java.lang.String removePrivateQueryParameters​(java.lang.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.