/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.catalina;

import java.io.InputStream;
import java.net.URL;
import java.util.List;
import java.util.Set;

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:

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

/**
 * 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:
 * <ol>
 * <li>Pre  - Resources defined by the &lt;PreResource&gt; element in the web
 *            application's context.xml. Resources will be searched in the order
 *            they were specified.</li>
 * <li>Main - The main resources for the web application - i.e. the WAR or the
 *            directory containing the expanded WAR</li>
 * <li>JARs - Resource JARs as defined by the Servlet specification. JARs will
 *            be searched in the order they were added to the ResourceRoot.</li>
 * <li>Post - Resources defined by the &lt;PostResource&gt; element in the web
 *            application's context.xml. Resources will be searched in the order
 *            they were specified.</li>
 * </ol>
 * The following conventions should be noted:
 * <ul>
 * <li>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.</li>
 * <li>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.</li>
 * <li>Only the main ResourceSet may define a META-INF/context.xml since that
 *     file defines the Pre- and Post-Resources.</li>
 * <li>As per the Servlet specification, any META-INF or WEB-INF directories in
 *     a resource JAR will be ignored.</li>
 * <li>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.
 * </ul>
 * This mechanism replaces and extends the following features that were present
 * in earlier versions:
 * <ul>
 * <li>Aliases               - Replaced by Post-Resources with the addition of
 *                             support for single files as well as directories
 *                             and JARs.</li>
 * <li>VirtualWebappLoader   - Replaced by Pre- and Post-Resources mapped to
 *                             WEB-INF/lib and WEB-INF/classes</li>
 * <li>VirtualDirContext     - Replaced by Pre- and Post-Resources</li>
 * <li>External repositories - Replaced by Pre- and Post-Resources mapped to
 *                             WEB-INF/lib and WEB-INF/classes</li>
 * <li>Resource JARs         - Same feature but implemented using the same
 *                             mechanism as all the other additional
 *                             resources.</li>
 * </ul>
 */
/*
 * A potential future enhancement is to allow writing to any ResourceSet,
 * not just the main ResourceSet although that adds all sorts complications
 * including:
 * - which ResourceSet to write to
 * - unexpected behaviour when deleting a resource from one ResourceSet since
 *   that may unmask a resource in a lower priority ResourceSet so what was a
 *   delete looks like a replace with the user having no idea where the 'new'
 *   resource came from
 * - how to handle PUT when the target is read-only but it could be written to
 *   a higher priority ResourceSet that is read-write
 */
public interface WebResourceRoot extends Lifecycle {
    
Obtain the object that represents the 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.
Params:
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/**
     * Obtain the object that represents the 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.
     *
     * @param path  The path for the resource of interest relative to the root
     *              of the web application. It must start with '/'.
     *
     * @return  The object that represents the resource at the given path
     */
    WebResource getResource(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 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)
Params:
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/**
     * Obtain the objects that represent the 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)
     *
     * @param path  The path for the resource of interest relative to the root
     *              of the web application. It must start with '/'.
     *
     * @return  The objects that represents the resource at the given path
     */
    WebResource[] getResources(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.
Params:
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/**
     * 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.
     *
     * @param path  The path of the class loader resource of interest relative
     *              to the the root of class loader resources for this web
     *              application.
     *
     * @return  The object that represents the class loader resource at the
     *          given path
     */
    WebResource getClassLoaderResource(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)
Params:
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/**
     * 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)
     *
     * @param 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 '/'.
     *
     * @return  The objects that represents the class loader resources at the
     *          given path
     */
    WebResource[] getClassLoaderResources(String path);

    
Obtain the list of the names of all of the files and directories located
in the specified directory.
Params:
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./**
     * Obtain the list of the names of all of the files and directories located
     * in the specified directory.
     *
     * @param path  The path for the resource of interest relative to the root
     *              of the web application. It must start with '/'.
     *
     * @return  The list of resources. If path does not refer to a directory
     *          then a zero length array will be returned.
     */
    String[] list(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.
Params:
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./**
     * 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.
     *
     * @param path  The path for the resource of interest relative to the root
     *              of the web application. It must start with '/'.
     *
     * @return  The Set of resources. If path does not refer to a directory
     *          then null will be returned.
     */
    Set<String> listWebAppPaths(String path);

    
Obtain the list of all of the WebResources in the specified directory.
Params:
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./**
     * Obtain the list of all of the WebResources in the specified directory.
     *
     * @param path  The path for the resource of interest relative to the root
     *              of the web application. It must start with '/'.
     *
     * @return  The list of resources. If path does not refer to a directory
     *          then a zero length array will be returned.
     */
    WebResource[] listResources(String path);

    
Create a new directory at the given path.
Params:
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/**
     * Create a new directory at the given path.
     *
     * @param path  The path for the new resource to create relative to the root
     *              of the web application. It must start with '/'.
     *
     * @return  <code>true</code> if the directory was created, otherwise
     *          <code>false</code>
     */
    boolean mkdir(String path);

    
Create a new resource at the requested path using the provided
InputStream.
Params:
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/**
     * Create a new resource at the requested path using the provided
     * InputStream.
     *
     * @param path      The path to be used for the new Resource. It is relative
     *                  to the root of the web application and must start with
     *                  '/'.
     * @param is        The InputStream that will provide the content for the
     *                  new Resource.
     * @param overwrite If <code>true</code> and the resource already exists it
     *                  will be overwritten. If <code>false</code> and the
     *                  resource already exists the write will fail.
     *
     * @return  <code>true</code> if and only if the new Resource is written
     */
    boolean write(String path, InputStream is, boolean overwrite);

    
Creates a new WebResourceSet for this WebResourceRoot based on the provided parameters. 
Params:
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 '/'./**
     * Creates a new {@link WebResourceSet} for this {@link WebResourceRoot}
     * based on the provided parameters.
     *
     * @param type          The type of {@link WebResourceSet} to create
     * @param webAppMount   The path within the web application that the
     *                          resources should be published at. It must start
     *                          with '/'.
     * @param url           The URL of the resource (must locate a JAR, file or
     *                          directory)
     * @param internalPath  The path within the resource where the content is to
     *                          be found. It must start with '/'.
     */
    void createWebResourceSet(ResourceSetType type, String webAppMount, URL url,
            String internalPath);

    
Creates a new WebResourceSet for this WebResourceRoot based on the provided parameters. 
Params:
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 '/'./**
     * Creates a new {@link WebResourceSet} for this {@link WebResourceRoot}
     * based on the provided parameters.
     *
     * @param type          The type of {@link WebResourceSet} to create
     * @param webAppMount   The path within the web application that the
     *                          resources should be published at. It must start
     *                          with '/'.
     * @param base          The location of the resources
     * @param 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 <code>null</code>.
     * @param internalPath  The path within the archive (or the resource if the
     *                          archivePath is <code>null</code> where the
     *                          content is to be found. It must start with '/'.
     */
    void createWebResourceSet(ResourceSetType type, String webAppMount,
            String base, String archivePath, String internalPath);


    
Adds the provided WebResourceSet to this web application as a 'Pre'
resource.
Params:
webResourceSet – the resource set to use/**
     * Adds the provided WebResourceSet to this web application as a 'Pre'
     * resource.
     *
     * @param webResourceSet the resource set to use
     */
    void addPreResources(WebResourceSet webResourceSet);

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

    
Adds the provided WebResourceSet to this web application as a 'Jar'
resource.
Params:
webResourceSet – the resource set to use/**
     * Adds the provided WebResourceSet to this web application as a 'Jar'
     * resource.
     *
     * @param webResourceSet the resource set to use
     */
    void addJarResources(WebResourceSet webResourceSet);

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

    
Adds the provided WebResourceSet to this web application as a 'Post'
resource.
Params:
webResourceSet – the resource set to use/**
     * Adds the provided WebResourceSet to this web application as a 'Post'
     * resource.
     *
     * @param webResourceSet the resource set to use
     */
    void addPostResources(WebResourceSet webResourceSet);

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

    
Returns:
the web application this WebResourceRoot is associated with./**
     * @return the web application this WebResourceRoot is associated with.
     */
    Context getContext();

    
Set the web application this WebResourceRoot is associated with.
Params:
context – the associated context/**
     * Set the web application this WebResourceRoot is associated with.
     *
     * @param context the associated context
     */
    void setContext(Context context);

    
Configure if this resources allow the use of symbolic links.
Params:
allowLinking –  true if symbolic links are allowed./**
     * Configure if this resources allow the use of symbolic links.
     *
     * @param allowLinking  <code>true</code> if symbolic links are allowed.
     */
    void setAllowLinking(boolean allowLinking);

    
Determine if this resources allow the use of symbolic links.
Returns:
 true if symbolic links are allowed/**
     * Determine if this resources allow the use of symbolic links.
     *
     * @return  <code>true</code> if symbolic links are allowed
     */
    boolean getAllowLinking();

    
Set whether or not caching is permitted for this web application.
Params:
cachingAllowed –    true to enable caching, else
                         false/**
     * Set whether or not caching is permitted for this web application.
     *
     * @param cachingAllowed    <code>true</code> to enable caching, else
     *                          <code>false</code>
     */
    void setCachingAllowed(boolean cachingAllowed);

    
Returns:
true if caching is permitted for this web application./**
     * @return <code>true</code> if caching is permitted for this web application.
     */
    boolean isCachingAllowed();

    
Set the Time-To-Live (TTL) for cache entries.
Params:
ttl –   TTL in milliseconds/**
     * Set the Time-To-Live (TTL) for cache entries.
     *
     * @param ttl   TTL in milliseconds
     */
    void setCacheTtl(long ttl);

    
Get the Time-To-Live (TTL) for cache entries.
Returns:
 TTL in milliseconds/**
     * Get the Time-To-Live (TTL) for cache entries.
     *
     * @return  TTL in milliseconds
     */
    long getCacheTtl();

    
Set the maximum permitted size for the cache.
Params:
cacheMaxSize –  Maximum cache size in kilobytes/**
     * Set the maximum permitted size for the cache.
     *
     * @param cacheMaxSize  Maximum cache size in kilobytes
     */
    void setCacheMaxSize(long cacheMaxSize);

    
Get the maximum permitted size for the cache.
Returns:
 Maximum cache size in kilobytes/**
     * Get the maximum permitted size for the cache.
     *
     * @return  Maximum cache size in kilobytes
     */
    long getCacheMaxSize();

    
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. 
Params:
cacheObjectMaxSize –    Maximum size for a single cached object in
                             kilobytes/**
     * Set the maximum permitted size for a single object in the cache. Note
     * that the maximum size in bytes may not exceed {@link Integer#MAX_VALUE}.
     *
     * @param cacheObjectMaxSize    Maximum size for a single cached object in
     *                              kilobytes
     */
    void setCacheObjectMaxSize(int cacheObjectMaxSize);

    
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/**
     * Get the maximum permitted size for a single object in the cache. Note
     * that the maximum size in bytes may not exceed {@link Integer#MAX_VALUE}.
     *
     * @return  Maximum size for a single cached object in kilobytes
     */
    int getCacheObjectMaxSize();

    
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.

Params:
trackLockedFiles – true to enable it, false to disable it/**
     * 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. {@link WebResource#getInputStream()}
     * will perform a number of additional tasks.
     * <ul>
     *   <li>The stack trace at the point where the method was called will be
     *       recorded and associated with the returned object.</li>
     *   <li>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.</li>
     *   <li>All remaining locked resources on web application shutdown will be
     *       logged and then closed.</li>
     * </ul>
     *
     * @param trackLockedFiles {@code true} to enable it, {@code false} to
     *                         disable it
     */
    void setTrackLockedFiles(boolean trackLockedFiles);

    
Has the track locked files feature been enabled?
Returns:
true if it has been enabled, otherwise false/**
     * Has the track locked files feature been enabled?
     *
     * @return {@code true} if it has been enabled, otherwise {@code false}
     */
    boolean getTrackLockedFiles();

    
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.
/**
     * 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 backgroundProcess();

    
Add a specified resource to track to be able to later release
resources on stop.
Params:
trackedResource – the resource that will be tracked/**
     * Add a specified resource to track to be able to later release
     * resources on stop.
     * @param trackedResource the resource that will be tracked
     */
    void registerTrackedResource(TrackedWebResource trackedResource);

    
Stop tracking specified resource, once it no longer needs to free resources.
Params:
trackedResource – the resource that was tracked/**
     * Stop tracking specified resource, once it no longer needs to free resources.
     * @param trackedResource the resource that was tracked
     */
    void deregisterTrackedResource(TrackedWebResource trackedResource);

    
Returns:
the set of WebResourceSet.getBaseUrl() for all WebResourceSets used by this root./**
     * @return the set of {@link WebResourceSet#getBaseUrl()} for all
     * {@link WebResourceSet}s used by this root.
     */
    List<URL> getBaseUrls();

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

    enum ResourceSetType {
        PRE,
        RESOURCE_JAR,
        POST,
        CLASSES_JAR
    }
}