Class ResourceCache

java.lang.Object
org.xmlresolver.CatalogManager
org.xmlresolver.cache.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.

Author:
ndw
  • Field Details

    • deleteWait

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

      public static final long cacheSize
      The maximum size of the cache (in files).
      See Also:
    • cacheSpace

      public static final long cacheSpace
      The maximum size of the cache (in bytes).
      See Also:
    • maxAge

      public static final long maxAge
      The maximum age of a file in the cache.
      See Also:
    • defaultPattern

      public static final String defaultPattern
      The default cache pattern.
      See Also:
    • excludedPatterns

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

  • Constructor Details

  • Method Details

    • 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 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 List<CacheInfo> getCacheInfoList()
    • getCacheInfo

      public CacheInfo getCacheInfo(String pattern)
    • getDefaultCacheInfo

      public CacheInfo getDefaultCacheInfo()
    • addCacheInfo

      public CacheInfo addCacheInfo(String pattern, boolean cache)
    • addCacheInfo

      public CacheInfo addCacheInfo(String pattern, boolean cache, long deleteWait, long cacheSize, long cacheSpace, long maxAge)
    • removeCacheInfo

      public void removeCacheInfo(String pattern)
    • entries

      public List<CacheEntry> entries()
    • expired

      public boolean expired(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(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 URI lookupURI(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 URI lookupNamespaceURI(String uri, String nature, 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 URI lookupPublic(String systemId, 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 URI lookupSystem(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(URI uri)
    • cachedNamespaceUri

      public CacheEntry cachedNamespaceUri(URI uri, String nature, String purpose)
    • cachedSystem

      public CacheEntry cachedSystem(URI systemId, String publicId)