Package org.apache.catalina

# Interface WebResourceRoot

All Superinterfaces:
  `Lifecycle`

All Known Implementing Classes:
  `ExtractingRoot`, `StandardRoot`

public interface WebResourceRoot extends Lifecycle
Represents the complete set of resources for a web application. The resources for a web application comprise of multiple ResourceSets and when looking for a Resource, the ResourceSets are processed in the following order:

1. Pre - Resources defined by the <PreResource> element in the web application's context.xml. Resources will be searched in the order they were specified.
2. Main - The main resources for the web application - i.e. the WAR or the directory containing the expanded WAR
3. JARs - Resource JARs as defined by the Servlet specification. JARs will be searched in the order they were added to the ResourceRoot.
4. Post - Resources defined by the <PostResource> element in the web application's context.xml. Resources will be searched in the order they were specified.

The following conventions should be noted:

- Write operations (including delete) will only be applied to the main ResourceSet. The write operation will fail if the presence of a Resource in one of the other ResourceSets effectively makes the operation on the main ResourceSet a NO-OP.
- A file in a ResourceSet will hide a directory of the same name (and all the contents of that directory) in a ResourceSet that is later in the search order.
- Only the main ResourceSet may define a META-INF/context.xml since that file defines the Pre- and Post-Resources.
- As per the Servlet specification, any META-INF or WEB-INF directories in a resource JAR will be ignored.
- Pre- and Post-Resources may define WEB-INF/lib and WEB-INF/classes in order to make additional libraries and/or classes available to the web application.

This mechanism replaces and extends the following features that were present in earlier versions:

- Aliases - Replaced by Post-Resources with the addition of support for single files as well as directories and JARs.
- VirtualWebappLoader - Replaced by Pre- and Post-Resources mapped to WEB-INF/lib and WEB-INF/classes
- VirtualDirContext - Replaced by Pre- and Post-Resources
- External repositories - Replaced by Pre- and Post-Resources mapped to WEB-INF/lib and WEB-INF/classes
- Resource JARs - Same feature but implemented using the same mechanism as all the other additional resources.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `WebResourceRoot.ArchiveIndexStrategy`
  `static interface`
  `WebResourceRoot.CacheStrategy`
  Provides a mechanism to modify the caching behaviour.
  `static enum`
  `WebResourceRoot.ResourceSetType`

  ### Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

  `Lifecycle.SingleUse`

- ## Field Summary

  ### Fields inherited from interface org.apache.catalina.Lifecycle

  `AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addJarResources(WebResourceSet webResourceSet)`
  Adds the provided WebResourceSet to this web application as a 'Jar' resource.
  `void`
  `addPostResources(WebResourceSet webResourceSet)`
  Adds the provided WebResourceSet to this web application as a 'Post' resource.
  `void`
  `addPreResources(WebResourceSet webResourceSet)`
  Adds the provided WebResourceSet to this web application as a 'Pre' resource.
  `void`
  `backgroundProcess()`
  This method will be invoked by the context on a periodic basis and allows the implementation a method that executes periodic tasks, such as purging expired cache entries.
  `void`
  `createWebResourceSet(WebResourceRoot.ResourceSetType type, String webAppMount, String base, String archivePath, String internalPath)`
  Creates a new `WebResourceSet` for this `WebResourceRoot` based on the provided parameters.
  `void`
  `createWebResourceSet(WebResourceRoot.ResourceSetType type, String webAppMount, URL url, String internalPath)`
  Creates a new `WebResourceSet` for this `WebResourceRoot` based on the provided parameters.
  `void`
  `deregisterTrackedResource(TrackedWebResource trackedResource)`
  Stop tracking specified resource, once it no longer needs to free resources.
  `void`
  `gc()`
  Implementations may cache some information to improve performance.
  `boolean`
  `getAllowLinking()`
  Determine if this resources allow the use of symbolic links.
  `String`
  `getArchiveIndexStrategy()`
  Get the strategy to use for the resources archive lookup.
  `WebResourceRoot.ArchiveIndexStrategy`
  `getArchiveIndexStrategyEnum()`
  Get the strategy to use for the resources archive lookup.
  `List<URL>`
  `getBaseUrls()`
  `long`
  `getCacheMaxSize()`
  Get the maximum permitted size for the cache.
  `int`
  `getCacheObjectMaxSize()`
  Get the maximum permitted size for a single object in the cache.
  `default WebResourceRoot.CacheStrategy`
  `getCacheStrategy()`
  Obtain the current caching strategy.
  `long`
  `getCacheTtl()`
  Get the Time-To-Live (TTL) for cache entries.
  `WebResource`
  `getClassLoaderResource(String path)`
  Obtain the object that represents the class loader resource at the given path.
  `WebResource[]`
  `getClassLoaderResources(String path)`
  Obtain the objects that represent the class loader resource at the given path.
  `Context`
  `getContext()`
  `WebResourceSet[]`
  `getJarResources()`
  `WebResourceSet[]`
  `getPostResources()`
  `WebResourceSet[]`
  `getPreResources()`
  `WebResource`
  `getResource(String path)`
  Obtain the object that represents the resource at the given path.
  `WebResource[]`
  `getResources(String path)`
  Obtain the objects that represent the resource at the given path.
  `boolean`
  `getTrackLockedFiles()`
  Has the track locked files feature been enabled?
  `boolean`
  `isCachingAllowed()`
  `String[]`
  `list(String path)`
  Obtain the list of the names of all of the files and directories located in the specified directory.
  `WebResource[]`
  `listResources(String path)`
  Obtain the list of all of the WebResources in the specified directory.
  `Set<String>`
  `listWebAppPaths(String path)`
  Obtain the Set of the web applications pathnames of all of the files and directories located in the specified directory.
  `boolean`
  `mkdir(String path)`
  Create a new directory at the given path.
  `void`
  `registerTrackedResource(TrackedWebResource trackedResource)`
  Add a specified resource to track to be able to later release resources on stop.
  `void`
  `setAllowLinking(boolean allowLinking)`
  Configure if this resources allow the use of symbolic links.
  `void`
  `setArchiveIndexStrategy(String archiveIndexStrategy)`
  Set the strategy to use for the resources archive lookup.
  `void`
  `setCacheMaxSize(long cacheMaxSize)`
  Set the maximum permitted size for the cache.
  `void`
  `setCacheObjectMaxSize(int cacheObjectMaxSize)`
  Set the maximum permitted size for a single object in the cache.
  `default void`
  `setCacheStrategy(WebResourceRoot.CacheStrategy strategy)`
  Set the current caching strategy.
  `void`
  `setCacheTtl(long ttl)`
  Set the Time-To-Live (TTL) for cache entries.
  `void`
  `setCachingAllowed(boolean cachingAllowed)`
  Set whether or not caching is permitted for this web application.
  `void`
  `setContext(Context context)`
  Set the web application this WebResourceRoot is associated with.
  `void`
  `setTrackLockedFiles(boolean trackLockedFiles)`
  Controls whether the track locked files feature is enabled.
  `boolean`
  `write(String path, InputStream is, boolean overwrite)`
  Create a new resource at the requested path using the provided InputStream.

  ### Methods inherited from interface org.apache.catalina.Lifecycle

  `addLifecycleListener, destroy, findLifecycleListeners, getState, getStateName, init, removeLifecycleListener, start, stop`

- ## Method Details

  - ### getResource

    WebResource getResource(String path)
    Obtain the object that represents the resource at the given path. Note that the resource at that path may not exist. If the resource does not exist, the WebResource returned will be associated with the main WebResourceSet.
    Parameters:
      `path` - The path for the resource of interest relative to the root of the web application. It must start with '/'.
    Returns:
      The object that represents the resource at the given path

  - ### getResources

    WebResource[] getResources(String path)
    Obtain the objects that represent the resource at the given path. Note that the resource at that path may not exist. If the resource does not exist, the WebResource returned will be associated with the main WebResourceSet. This will include all matches even if the resource would not normally be accessible (e.g. because it was overridden by another resource)
    Parameters:
      `path` - The path for the resource of interest relative to the root of the web application. It must start with '/'.
    Returns:
      The objects that represents the resource at the given path

  - ### getClassLoaderResource

    WebResource getClassLoaderResource(String path)
    Obtain the object that represents the class loader resource at the given path. WEB-INF/classes is always searched prior to searching JAR files in WEB-INF/lib. The search order for JAR files will be consistent across subsequent calls to this method until the web application is reloaded. No guarantee is made as to what the search order for JAR files may be.
    Parameters:
      `path` - The path of the class loader resource of interest relative to the the root of class loader resources for this web application.
    Returns:
      The object that represents the class loader resource at the given path

  - ### getClassLoaderResources

    WebResource[] getClassLoaderResources(String path)
    Obtain the objects that represent the class loader resource at the given path. Note that the resource at that path may not exist. If the path does not exist, the WebResource returned will be associated with the main WebResourceSet. This will include all matches even if the resource would not normally be accessible (e.g. because it was overridden by another resource)
    Parameters:
      `path` - The path for the class loader resource of interest relative to the root of the class loader resources for the web application. It must start with '/'.
    Returns:
      The objects that represents the class loader resources at the given path. There will always be at least one element although that element may represent a resource that is not present.

  - ### list

    String[] list(String path)
    Obtain the list of the names of all of the files and directories located in the specified directory.
    Parameters:
      `path` - The path for the resource of interest relative to the root of the web application. It must start with '/'.
    Returns:
      The list of resources. If path does not refer to a directory then a zero length array will be returned.

  - ### listWebAppPaths

    Set<String> listWebAppPaths(String path)
    Obtain the Set of the web applications pathnames of all of the files and directories located in the specified directory. Paths representing directories will end with a '/' character.
    Parameters:
      `path` - The path for the resource of interest relative to the root of the web application. It must start with '/'.
    Returns:
      The Set of resources. If path does not refer to a directory then null will be returned.

  - ### listResources

    WebResource[] listResources(String path)
    Obtain the list of all of the WebResources in the specified directory.
    Parameters:
      `path` - The path for the resource of interest relative to the root of the web application. It must start with '/'.
    Returns:
      The list of resources. If path does not refer to a directory then a zero length array will be returned.

  - ### mkdir

    boolean mkdir(String path)
    Create a new directory at the given path.
    Parameters:
      `path` - The path for the new resource to create relative to the root of the web application. It must start with '/'.
    Returns:
      `true` if the directory was created, otherwise `false`

  - ### write

    boolean write(String path, InputStream is, boolean overwrite)
    Create a new resource at the requested path using the provided InputStream.
    Parameters:
      `path` - The path to be used for the new Resource. It is relative to the root of the web application and must start with '/'.
      `is` - The InputStream that will provide the content for the new Resource.
      `overwrite` - If `true` and the resource already exists it will be overwritten. If `false` and the resource already exists the write will fail.
    Returns:
      `true` if and only if the new Resource is written

  - ### createWebResourceSet

    void createWebResourceSet(WebResourceRoot.ResourceSetType type, String webAppMount, URL url, String internalPath)
    Creates a new `WebResourceSet` for this `WebResourceRoot` based on the provided parameters.
    Parameters:
      `type` - The type of `WebResourceSet` to create
      `webAppMount` - The path within the web application that the resources should be published at. It must start with '/'.
      `url` - The URL of the resource (must locate a JAR, file or directory)
      `internalPath` - The path within the resource where the content is to be found. It must start with '/'.

  - ### createWebResourceSet

    void createWebResourceSet(WebResourceRoot.ResourceSetType type, String webAppMount, String base, String archivePath, String internalPath)
    Creates a new `WebResourceSet` for this `WebResourceRoot` based on the provided parameters.
    Parameters:
      `type` - The type of `WebResourceSet` to create
      `webAppMount` - The path within the web application that the resources should be published at. It must start with '/'.
      `base` - The location of the resources
      `archivePath` - The path within the resource to the archive where the content is to be found. If there is no archive then this should be `null`.
      `internalPath` - The path within the archive (or the resource if the archivePath is `null` where the content is to be found. It must start with '/'.

  - ### addPreResources

    void addPreResources(WebResourceSet webResourceSet)
    Adds the provided WebResourceSet to this web application as a 'Pre' resource.
    Parameters:
      `webResourceSet` - the resource set to use

  - ### getPreResources

    WebResourceSet[] getPreResources()
    Returns:
      the list of WebResourceSet configured to this web application as a 'Pre' resource.

  - ### addJarResources

    void addJarResources(WebResourceSet webResourceSet)
    Adds the provided WebResourceSet to this web application as a 'Jar' resource.
    Parameters:
      `webResourceSet` - the resource set to use

  - ### getJarResources

    WebResourceSet[] getJarResources()
    Returns:
      the list of WebResourceSet configured to this web application as a 'Jar' resource.

  - ### addPostResources

    void addPostResources(WebResourceSet webResourceSet)
    Adds the provided WebResourceSet to this web application as a 'Post' resource.
    Parameters:
      `webResourceSet` - the resource set to use

  - ### getPostResources

    WebResourceSet[] getPostResources()
    Returns:
      the list of WebResourceSet configured to this web application as a 'Post' resource.

  - ### getContext

    Context getContext()
    Returns:
      the web application this WebResourceRoot is associated with.

  - ### setContext

    void setContext(Context context)
    Set the web application this WebResourceRoot is associated with.
    Parameters:
      `context` - the associated context

  - ### setAllowLinking

    void setAllowLinking(boolean allowLinking)
    Configure if this resources allow the use of symbolic links.
    Parameters:
      `allowLinking` - `true` if symbolic links are allowed.

  - ### getAllowLinking

    boolean getAllowLinking()
    Determine if this resources allow the use of symbolic links.
    Returns:
      `true` if symbolic links are allowed

  - ### setCachingAllowed

    void setCachingAllowed(boolean cachingAllowed)
    Set whether or not caching is permitted for this web application.
    Parameters:
      `cachingAllowed` - `true` to enable caching, else `false`

  - ### isCachingAllowed

    boolean isCachingAllowed()
    Returns:
      `true` if caching is permitted for this web application.

  - ### setCacheTtl

    void setCacheTtl(long ttl)
    Set the Time-To-Live (TTL) for cache entries.
    Parameters:
      `ttl` - TTL in milliseconds

  - ### getCacheTtl

    long getCacheTtl()
    Get the Time-To-Live (TTL) for cache entries.
    Returns:
      TTL in milliseconds

  - ### setCacheMaxSize

    void setCacheMaxSize(long cacheMaxSize)
    Set the maximum permitted size for the cache.
    Parameters:
      `cacheMaxSize` - Maximum cache size in kilobytes

  - ### getCacheMaxSize

    long getCacheMaxSize()
    Get the maximum permitted size for the cache.
    Returns:
      Maximum cache size in kilobytes

  - ### setCacheObjectMaxSize

    void setCacheObjectMaxSize(int cacheObjectMaxSize)
    Set the maximum permitted size for a single object in the cache. Note that the maximum size in bytes may not exceed `Integer.MAX_VALUE`.
    Parameters:
      `cacheObjectMaxSize` - Maximum size for a single cached object in kilobytes

  - ### getCacheObjectMaxSize

    int getCacheObjectMaxSize()
    Get the maximum permitted size for a single object in the cache. Note that the maximum size in bytes may not exceed `Integer.MAX_VALUE`.
    Returns:
      Maximum size for a single cached object in kilobytes

  - ### setTrackLockedFiles

    void setTrackLockedFiles(boolean trackLockedFiles)
    Controls whether the track locked files feature is enabled. If enabled, all calls to methods that return objects that lock a file and need to be closed to release that lock (e.g. `WebResource.getInputStream()` will perform a number of additional tasks.
    - The stack trace at the point where the method was called will be recorded and associated with the returned object.
    - The returned object will be wrapped so that the point where close() (or equivalent) is called to release the resources can be detected. Tracking of the object will cease once the resources have been released.
    - All remaining locked resources on web application shutdown will be logged and then closed.
    Parameters:
      `trackLockedFiles` - `true` to enable it, `false` to disable it

  - ### getTrackLockedFiles

    boolean getTrackLockedFiles()
    Has the track locked files feature been enabled?
    Returns:
      `true` if it has been enabled, otherwise `false`

  - ### setArchiveIndexStrategy

    void setArchiveIndexStrategy(String archiveIndexStrategy)
    Set the strategy to use for the resources archive lookup.
    Parameters:
      `archiveIndexStrategy` - The strategy to use for the resources archive lookup

  - ### getArchiveIndexStrategy

    String getArchiveIndexStrategy()
    Get the strategy to use for the resources archive lookup.
    Returns:
      The strategy to use for the resources archive lookup

  - ### getArchiveIndexStrategyEnum

    WebResourceRoot.ArchiveIndexStrategy getArchiveIndexStrategyEnum()
    Get the strategy to use for the resources archive lookup.
    Returns:
      The strategy to use for the resources archive lookup

  - ### backgroundProcess

    void backgroundProcess()
    This method will be invoked by the context on a periodic basis and allows the implementation a method that executes periodic tasks, such as purging expired cache entries.

  - ### registerTrackedResource

    void registerTrackedResource(TrackedWebResource trackedResource)
    Add a specified resource to track to be able to later release resources on stop.
    Parameters:
      `trackedResource` - the resource that will be tracked

  - ### deregisterTrackedResource

    void deregisterTrackedResource(TrackedWebResource trackedResource)
    Stop tracking specified resource, once it no longer needs to free resources.
    Parameters:
      `trackedResource` - the resource that was tracked

  - ### getBaseUrls

    List<URL> getBaseUrls()
    Returns:
      the set of `WebResourceSet.getBaseUrl()` for all `WebResourceSet`s used by this root.

  - ### gc

    void gc()
    Implementations may cache some information to improve performance. This method triggers the clean-up of those resources.

  - ### getCacheStrategy

    default WebResourceRoot.CacheStrategy getCacheStrategy()
    Obtain the current caching strategy.

    The default implementation returns `null`. Sub-classes wishing to utilise a `WebResourceRoot.CacheStrategy` should provide an appropriate implementation.

    Returns:
      the current caching strategy or `null` if no strategy has been configured

  - ### setCacheStrategy

    default void setCacheStrategy(WebResourceRoot.CacheStrategy strategy)
    Set the current caching strategy.

    The default implementation is a NO-OP. Sub-classes wishing to utilise a `WebResourceRoot.CacheStrategy` should provide an appropriate implementation.

    Parameters:
      `strategy` - The new strategy to use or `null` for no strategy