Package org.xmlresolver.cache

Class ResourceCache

  • All Implemented Interfaces:
    XMLCatalogResolver
    public class ResourceCache
extends CatalogManager
    Implements a resource cache.

    Resources added to the cache are stored locally. Access to the cache is through an OASIS XML Catalog returned by the catalog() method. After a catalog search that includes the cache catalog, you can test if the local copy of the resource is expired. If it is, it will be removed from the cache.

    Implementation details

    The underlying cache is implemented using the filesystem. A cache directory must be given when the cache is created. The ResourceCache must have write access to the directory. The directory specified should be used exclusively for the cache in order to avoid filename collisions and other errors.

    The cache uses three subdirectories and two files:

    • Catalog entries for files in the cache are stored in the entry directory.
    • The actual resources are stored in the data directory.
    • Expired entries are stored in expired.
    • The lock file is used to maintain synchronized access to the cache directory (multiple threads and even multiple applications running perhaps in different VMs can share the same cache directory).
    • The control.xml file can be used to configure the cache.

    When a resource is added to the cache, the data is stored in the data directory and a catalog entry is created in the entry directory. After the entry has been added, the next request for the catalog will include this entry.

    When a resource expires, its catalog entry file is moved to the expired directory. The actual data is not removed right away because other caches may still have that entry in their catalog.

    During catalog initialization, all of the the expired entries are scanned. If any of them are older than a "delete wait" threshold, they are deleted along with their data.

    The cache control file contains caching parameters:

    <cache-control xmlns="http://xmlresolver.org/ns/cache"
               max-age="86400" delete-wait="86400"
               size="1500" space="10m">
 <cache uri="http://www.w3.org/" max-age="172800" space="500k"/>
 <no-cache uri="http://localhost/"/>
 <cache uri="http://www.flickr.com/" max-age="0"/>
 <cache uri="http://flickr.com/" max-age="0"/>
 </cache-control>

    If definitive information about the age of a resource cannot be determined and it is older than "max-age", it will be treated as out-of-date and its cached entry will be updated.

    Entries in the cache are sorted by age. If the cache exceeds "size" entries or "space" bytes of storage, then the oldest entries are deleted.

    The cache and no-cache elements match URIs by regular expression. If a no-cache entry matches, then the URI is not cached. If no entry matches, the default is to cache with the parameters specified on the cache-control element.

    • Field Detail

      • deleteWait

        public static final long deleteWait
        Length of time a cached resource remains available after it has been deleted.
        See Also:
        Constant Field Values

      • cacheSize

        public static final long cacheSize
        The maximum size of the cache (in files).
        See Also:
        Constant Field Values

      • cacheSpace

        public static final long cacheSpace
        The maximum size of the cache (in bytes).
        See Also:
        Constant Field Values

      • maxAge

        public static final long maxAge
        The maximum age of a file in the cache.
        See Also:
        Constant Field Values

      • defaultPattern

        public static final java.lang.String defaultPattern
        The default cache pattern.
        See Also:
        Constant Field Values

      • excludedPatterns

        public static final java.lang.String[] excludedPatterns
        Excluded patterns.

        These patterns are excluded because they refer to files on the local filesystem. If they are cached, then the resolver may resolve URIs from the cache that are "stale" with respect to the files actually on the filesystem.

        The jar:file: and classpath: schemes are Java schemes.

        The path: scheme as a .NET scheme (similar in effect to classpath:).

        Both the Java and .NET schemes are excluded in case the cache is shared across languages.

    • Method Detail

      • reset

        public void reset()
        Reset the cache configuration.

        If the cache configuration is changed, calling reset will adjust this cache to reflect the new settings.

      • directory

        public java.lang.String directory()
        Returns the cache directory associated with this ResourceCache.
        Returns:
        The absolute path of the cache directory, or null if it could not be configured with the requested directory.

      • getCacheInfoList

        public java.util.List<CacheInfo> getCacheInfoList()

      • getCacheInfo

        public CacheInfo getCacheInfo​(java.lang.String pattern)

      • getDefaultCacheInfo

        public CacheInfo getDefaultCacheInfo()

      • addCacheInfo

        public CacheInfo addCacheInfo​(java.lang.String pattern,
                              boolean cache)

      • addCacheInfo

        public CacheInfo addCacheInfo​(java.lang.String pattern,
                              boolean cache,
                              long deleteWait,
                              long cacheSize,
                              long cacheSpace,
                              long maxAge)

      • removeCacheInfo

        public void removeCacheInfo​(java.lang.String pattern)

      • entries

        public java.util.List<CacheEntry> entries()

      • expired

        public boolean expired​(java.net.URI local)
        Attempts to determine if the local copy is out of date.

        N.B. Calling this function will remove expired entries from the cache!

        If the URI is an http: URI, a HEAD request is made and the cachedTime() and etag are compared. If the resource on the web is more recent, true is returned.

        If the resource isn't cached, isn't an http: URI, or an error occurs attempting to get the HEAD, then false is returned.

        Parameters:
        local - The local URI as found in cache.
        Returns:
        True if and only if the resource is expired.

      • cacheURI

        public boolean cacheURI​(java.lang.String uri)
        Returns true if the specified absolute URI should be cached.
        Parameters:
        uri - The URI
        Returns:
        Whether or not it should be cached

      • lookupURI

        public java.net.URI lookupURI​(java.lang.String uri)
        Description copied from class: CatalogManager
        Lookup the specified URI in the catalog.

        If a URI entry exists in the catalog for the URI specified, return the mapped value.

        Specified by:
        lookupURI in interface XMLCatalogResolver
        Overrides:
        lookupURI in class CatalogManager
        Parameters:
        uri - The URI to locate in the catalog.
        Returns:
        The mapped value, or null if no matching entry is found.

      • lookupNamespaceURI

        public java.net.URI lookupNamespaceURI​(java.lang.String uri,
                                       java.lang.String nature,
                                       java.lang.String purpose)
        Description copied from class: CatalogManager
        Lookup the specified namespace URI in the catalog.

        If a URI entry exists in the catalog for the URI specified, and with the specified nature and purpose, return the mapped value.

        Overrides:
        lookupNamespaceURI in class CatalogManager
        Parameters:
        uri - The URI to locate in the catalog.
        nature - The RDDL nature of the requested resource
        purpose - The RDDL purpose of the requested resource
        Returns:
        The mapped value, or null if no matching entry is found.

      • lookupPublic

        public java.net.URI lookupPublic​(java.lang.String systemId,
                                 java.lang.String publicId)
        Description copied from class: CatalogManager
        Lookup the specified system and public identifiers in the catalog.

        If a SYSTEM or PUBLIC entry exists in the catalog for the system and public identifiers specified, return the mapped value.

        On Windows and MacOS operating systems, the comparison between the system identifier provided and the SYSTEM entries in the Catalog is case-insensitive.

        Specified by:
        lookupPublic in interface XMLCatalogResolver
        Overrides:
        lookupPublic in class CatalogManager
        Parameters:
        systemId - The nominal system identifier for the entity in question (as provided in the source document).
        publicId - The public identifier to locate in the catalog. Public identifiers are normalized before comparison.
        Returns:
        The mapped value, or null if no matching entry is found.

      • lookupSystem

        public java.net.URI lookupSystem​(java.lang.String systemId)
        Description copied from class: CatalogManager
        Lookup the specified system identifier in the catalog.

        If a SYSTEM entry exists in the catalog for the system identifier specified, return the mapped value.

        On Windows-based operating systems, the comparison between the system identifier provided and the SYSTEM entries in the Catalog is case-insensitive.

        Specified by:
        lookupSystem in interface XMLCatalogResolver
        Overrides:
        lookupSystem in class CatalogManager
        Parameters:
        systemId - The system identifier to locate in the catalog.
        Returns:
        The mapped value, or null if no matching entry is found.

      • cachedUri

        public CacheEntry cachedUri​(java.net.URI uri)

      • cachedNamespaceUri

        public CacheEntry cachedNamespaceUri​(java.net.URI uri,
                                     java.lang.String nature,
                                     java.lang.String purpose)

      • cachedSystem

        public CacheEntry cachedSystem​(java.net.URI systemId,
                               java.lang.String publicId)