All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.apache.catalina.WebResourceRoot Maven / Gradle / Ivy

There is a newer version: 11.0.0-M26
Show newest version
/*
 * 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:
 * 
    *
  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. *
  3. Main - The main resources for the web application - i.e. the WAR or the directory containing the expanded * WAR
  4. *
  5. JARs - Resource JARs as defined by the Servlet specification. JARs will be searched in the order they were added * to the ResourceRoot.
  6. *
  7. Post - Resources defined by the <PostResource> element in the web application's context.xml. Resources will * be searched in the order they were specified.
  8. *
* 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.
  • *
*/ /* * 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 resource 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 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) * * @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. * * @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) * * @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. There will always be at least * one element although that element may represent a resource that is not present. */ WebResource[] getClassLoaderResources(String path); /** * 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. * * @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 listWebAppPaths(String path); /** * 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. * * @param path The path for the new resource to create relative to the root of the web application. It must start * with '/'. * * @return true if the directory was created, otherwise false */ boolean mkdir(String path); /** * 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 true and the resource already exists it will be overwritten. If * false and the resource already exists the write will fail. * * @return true if and only if the new Resource is written */ boolean write(String path, InputStream is, boolean overwrite); /** * 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 {@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 null. * @param 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 '/'. */ void createWebResourceSet(ResourceSetType type, String webAppMount, String base, String archivePath, String internalPath); /** * Adds the provided WebResourceSet to this web application as a 'Pre' resource. * * @param webResourceSet the resource set to use */ void addPreResources(WebResourceSet webResourceSet); /** * @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. * * @param webResourceSet the resource set to use */ void addJarResources(WebResourceSet webResourceSet); /** * @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. * * @param webResourceSet the resource set to use */ void addPostResources(WebResourceSet webResourceSet); /** * @return the list of WebResourceSet configured to this web application as a 'Post' resource. */ WebResourceSet[] getPostResources(); /** * @return the web application this WebResourceRoot is associated with. */ Context getContext(); /** * 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. * * @param allowLinking true if symbolic links are allowed. */ void setAllowLinking(boolean allowLinking); /** * Determine if this resources allow the use of symbolic links. * * @return true if symbolic links are allowed */ boolean getAllowLinking(); /** * Set whether or not caching is permitted for this web application. * * @param cachingAllowed true to enable caching, else false */ void setCachingAllowed(boolean cachingAllowed); /** * @return true if caching is permitted for this web application. */ boolean isCachingAllowed(); /** * 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. * * @return TTL in milliseconds */ long getCacheTtl(); /** * 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. * * @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 {@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 {@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. {@link 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.
  • *
* * @param trackLockedFiles {@code true} to enable it, {@code false} to disable it */ void setTrackLockedFiles(boolean trackLockedFiles); /** * Has the track locked files feature been enabled? * * @return {@code true} if it has been enabled, otherwise {@code false} */ boolean getTrackLockedFiles(); /** * Set the strategy to use for the resources archive lookup. * * @param archiveIndexStrategy The strategy to use for the resources archive lookup */ void setArchiveIndexStrategy(String archiveIndexStrategy); /** * Get the strategy to use for the resources archive lookup. * * @return The strategy to use for the resources archive lookup */ String getArchiveIndexStrategy(); /** * Get the strategy to use for the resources archive lookup. * * @return The strategy to use for the resources archive lookup */ ArchiveIndexStrategy getArchiveIndexStrategyEnum(); /** * 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. * * @param trackedResource the resource that will be tracked */ void registerTrackedResource(TrackedWebResource trackedResource); /** * Stop tracking specified resource, once it no longer needs to free resources. * * @param trackedResource the resource that was tracked */ void deregisterTrackedResource(TrackedWebResource trackedResource); /** * @return the set of {@link WebResourceSet#getBaseUrl()} for all {@link WebResourceSet}s used by this root. */ List getBaseUrls(); /** * Implementations may cache some information to improve performance. This method triggers the clean-up of those * resources. */ void gc(); /** * Obtain the current caching strategy. *

* The default implementation returns {@code null}. Sub-classes wishing to utilise a {@link CacheStrategy} should * provide an appropriate implementation. * * @return the current caching strategy or {@code null} if no strategy has been configured */ default CacheStrategy getCacheStrategy() { return null; } /** * Set the current caching strategy. *

* The default implementation is a NO-OP. Sub-classes wishing to utilise a {@link CacheStrategy} should provide an * appropriate implementation. * * @param strategy The new strategy to use or {@code null} for no strategy */ default void setCacheStrategy(CacheStrategy strategy) { // NO-OP } enum ResourceSetType { PRE, RESOURCE_JAR, POST, CLASSES_JAR } enum ArchiveIndexStrategy { SIMPLE(false, false), BLOOM(true, true), PURGED(true, false); private final boolean usesBloom; private final boolean retain; ArchiveIndexStrategy(boolean usesBloom, boolean retain) { this.usesBloom = usesBloom; this.retain = retain; } public boolean getUsesBloom() { return usesBloom; } public boolean getRetain() { return retain; } } /** * Provides a mechanism to modify the caching behaviour. */ interface CacheStrategy { /** * Should the result of looking up the resource at the given path be excluded from caching? * * @param path The path to check against the strategy to see if the result should be cached * * @return {@code true} if the result should not be cached, otherwise {@code false} */ boolean noCache(String path); } }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy