Class StandardRoot

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.util.LifecycleMBeanBase
org.apache.catalina.webresources.StandardRoot
All Implemented Interfaces:
MBeanRegistration, JmxEnabled, Lifecycle, WebResourceRoot
Direct Known Subclasses:
ExtractingRoot
public class StandardRoot extends LifecycleMBeanBase implements WebResourceRoot

Provides the resources implementation for a web application. The Lifecycle of this class should be aligned with that of the associated Context.

This implementation assumes that the base attribute supplied to createWebResourceSet(org.apache.catalina.WebResourceRoot.ResourceSetType, String, String, String, String) represents the absolute path to a file.

  • Field Details

  • Constructor Details

    • StandardRoot

      public StandardRoot()
      Creates a new standard implementation of WebResourceRoot. A no argument constructor is required for this to work with the digester. setContext(Context) must be called before this component is initialized.

    • StandardRoot

      public StandardRoot(Context context)

  • Method Details

    • list

      public String[] list(String path)
      Description copied from interface: WebResourceRoot
      Obtain the list of the names of all of the files and directories located in the specified directory.
      Specified by:
      list in interface WebResourceRoot
      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

      public Set<String> listWebAppPaths(String path)
      Description copied from interface: WebResourceRoot
      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.
      Specified by:
      listWebAppPaths in interface WebResourceRoot
      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.

    • mkdir

      public boolean mkdir(String path)
      Description copied from interface: WebResourceRoot
      Create a new directory at the given path.
      Specified by:
      mkdir in interface WebResourceRoot
      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

      public boolean write(String path, InputStream is, boolean overwrite)
      Description copied from interface: WebResourceRoot
      Create a new resource at the requested path using the provided InputStream.
      Specified by:
      write in interface WebResourceRoot
      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

    • getResource

      public WebResource getResource(String path)
      Description copied from interface: WebResourceRoot
      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.
      Specified by:
      getResource in interface WebResourceRoot
      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

    • getResource

      protected WebResource getResource(String path, boolean validate, boolean useClassLoaderResources)

    • getClassLoaderResource

      public WebResource getClassLoaderResource(String path)
      Description copied from interface: WebResourceRoot
      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.
      Specified by:
      getClassLoaderResource in interface WebResourceRoot
      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

      public WebResource[] getClassLoaderResources(String path)
      Description copied from interface: WebResourceRoot
      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)
      Specified by:
      getClassLoaderResources in interface WebResourceRoot
      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.

    • getResourceInternal

      protected final WebResource getResourceInternal(String path, boolean useClassLoaderResources)

    • getResources

      public WebResource[] getResources(String path)
      Description copied from interface: WebResourceRoot
      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)
      Specified by:
      getResources in interface WebResourceRoot
      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

    • getResourcesInternal

      protected WebResource[] getResourcesInternal(String path, boolean useClassLoaderResources)

    • listResources

      public WebResource[] listResources(String path)
      Description copied from interface: WebResourceRoot
      Obtain the list of all of the WebResources in the specified directory.
      Specified by:
      listResources in interface WebResourceRoot
      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.

    • listResources

      protected WebResource[] listResources(String path, boolean validate)

    • createWebResourceSet

      public void createWebResourceSet(WebResourceRoot.ResourceSetType type, String webAppMount, URL url, String internalPath)
      Description copied from interface: WebResourceRoot
      Creates a new WebResourceSet for this WebResourceRoot based on the provided parameters.
      Specified by:
      createWebResourceSet in interface WebResourceRoot
      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

      public void createWebResourceSet(WebResourceRoot.ResourceSetType type, String webAppMount, String base, String archivePath, String internalPath)
      Description copied from interface: WebResourceRoot
      Creates a new WebResourceSet for this WebResourceRoot based on the provided parameters.
      Specified by:
      createWebResourceSet in interface WebResourceRoot
      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

      public void addPreResources(WebResourceSet webResourceSet)
      Description copied from interface: WebResourceRoot
      Adds the provided WebResourceSet to this web application as a 'Pre' resource.
      Specified by:
      addPreResources in interface WebResourceRoot
      Parameters:
      webResourceSet - the resource set to use

    • getPreResources

      public WebResourceSet[] getPreResources()
      Specified by:
      getPreResources in interface WebResourceRoot
      Returns:
      the list of WebResourceSet configured to this web application as a 'Pre' resource.

    • addJarResources

      public void addJarResources(WebResourceSet webResourceSet)
      Description copied from interface: WebResourceRoot
      Adds the provided WebResourceSet to this web application as a 'Jar' resource.
      Specified by:
      addJarResources in interface WebResourceRoot
      Parameters:
      webResourceSet - the resource set to use

    • getJarResources

      public WebResourceSet[] getJarResources()
      Specified by:
      getJarResources in interface WebResourceRoot
      Returns:
      the list of WebResourceSet configured to this web application as a 'Jar' resource.

    • addPostResources

      public void addPostResources(WebResourceSet webResourceSet)
      Description copied from interface: WebResourceRoot
      Adds the provided WebResourceSet to this web application as a 'Post' resource.
      Specified by:
      addPostResources in interface WebResourceRoot
      Parameters:
      webResourceSet - the resource set to use

    • getPostResources

      public WebResourceSet[] getPostResources()
      Specified by:
      getPostResources in interface WebResourceRoot
      Returns:
      the list of WebResourceSet configured to this web application as a 'Post' resource.

    • getClassResources

      protected WebResourceSet[] getClassResources()

    • addClassResources

      protected void addClassResources(WebResourceSet webResourceSet)

    • setAllowLinking

      public void setAllowLinking(boolean allowLinking)
      Description copied from interface: WebResourceRoot
      Configure if this resources allow the use of symbolic links.
      Specified by:
      setAllowLinking in interface WebResourceRoot
      Parameters:
      allowLinking - true if symbolic links are allowed.

    • getAllowLinking

      public boolean getAllowLinking()
      Description copied from interface: WebResourceRoot
      Determine if this resources allow the use of symbolic links.
      Specified by:
      getAllowLinking in interface WebResourceRoot
      Returns:
      true if symbolic links are allowed

    • setCachingAllowed

      public void setCachingAllowed(boolean cachingAllowed)
      Description copied from interface: WebResourceRoot
      Set whether or not caching is permitted for this web application.
      Specified by:
      setCachingAllowed in interface WebResourceRoot
      Parameters:
      cachingAllowed - true to enable caching, else false

    • isCachingAllowed

      public boolean isCachingAllowed()
      Specified by:
      isCachingAllowed in interface WebResourceRoot
      Returns:
      true if caching is permitted for this web application.

    • getCacheStrategy

      public WebResourceRoot.CacheStrategy getCacheStrategy()
      Description copied from interface: WebResourceRoot
      Obtain the current caching strategy.

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

      Specified by:
      getCacheStrategy in interface WebResourceRoot
      Returns:
      the current caching strategy or null if no strategy has been configured

    • setCacheStrategy

      public void setCacheStrategy(WebResourceRoot.CacheStrategy strategy)
      Description copied from interface: WebResourceRoot
      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.

      Specified by:
      setCacheStrategy in interface WebResourceRoot
      Parameters:
      strategy - The new strategy to use or null for no strategy

    • getCacheTtl

      public long getCacheTtl()
      Description copied from interface: WebResourceRoot
      Get the Time-To-Live (TTL) for cache entries.
      Specified by:
      getCacheTtl in interface WebResourceRoot
      Returns:
      TTL in milliseconds

    • setCacheTtl

      public void setCacheTtl(long cacheTtl)
      Description copied from interface: WebResourceRoot
      Set the Time-To-Live (TTL) for cache entries.
      Specified by:
      setCacheTtl in interface WebResourceRoot
      Parameters:
      cacheTtl - TTL in milliseconds

    • getCacheMaxSize

      public long getCacheMaxSize()
      Description copied from interface: WebResourceRoot
      Get the maximum permitted size for the cache.
      Specified by:
      getCacheMaxSize in interface WebResourceRoot
      Returns:
      Maximum cache size in kilobytes

    • setCacheMaxSize

      public void setCacheMaxSize(long cacheMaxSize)
      Description copied from interface: WebResourceRoot
      Set the maximum permitted size for the cache.
      Specified by:
      setCacheMaxSize in interface WebResourceRoot
      Parameters:
      cacheMaxSize - Maximum cache size in kilobytes

    • setCacheObjectMaxSize

      public void setCacheObjectMaxSize(int cacheObjectMaxSize)
      Description copied from interface: WebResourceRoot
      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.
      Specified by:
      setCacheObjectMaxSize in interface WebResourceRoot
      Parameters:
      cacheObjectMaxSize - Maximum size for a single cached object in kilobytes

    • getCacheObjectMaxSize

      public int getCacheObjectMaxSize()
      Description copied from interface: WebResourceRoot
      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.
      Specified by:
      getCacheObjectMaxSize in interface WebResourceRoot
      Returns:
      Maximum size for a single cached object in kilobytes

    • setTrackLockedFiles

      public void setTrackLockedFiles(boolean trackLockedFiles)
      Description copied from interface: WebResourceRoot
      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.
      Specified by:
      setTrackLockedFiles in interface WebResourceRoot
      Parameters:
      trackLockedFiles - true to enable it, false to disable it

    • getTrackLockedFiles

      public boolean getTrackLockedFiles()
      Description copied from interface: WebResourceRoot
      Has the track locked files feature been enabled?
      Specified by:
      getTrackLockedFiles in interface WebResourceRoot
      Returns:
      true if it has been enabled, otherwise false

    • setArchiveIndexStrategy

      public void setArchiveIndexStrategy(String archiveIndexStrategy)
      Description copied from interface: WebResourceRoot
      Set the strategy to use for the resources archive lookup.
      Specified by:
      setArchiveIndexStrategy in interface WebResourceRoot
      Parameters:
      archiveIndexStrategy - The strategy to use for the resources archive lookup

    • getArchiveIndexStrategy

      public String getArchiveIndexStrategy()
      Description copied from interface: WebResourceRoot
      Get the strategy to use for the resources archive lookup.
      Specified by:
      getArchiveIndexStrategy in interface WebResourceRoot
      Returns:
      The strategy to use for the resources archive lookup

    • getArchiveIndexStrategyEnum

      public WebResourceRoot.ArchiveIndexStrategy getArchiveIndexStrategyEnum()
      Description copied from interface: WebResourceRoot
      Get the strategy to use for the resources archive lookup.
      Specified by:
      getArchiveIndexStrategyEnum in interface WebResourceRoot
      Returns:
      The strategy to use for the resources archive lookup

    • getTrackedResources

      public List<String> getTrackedResources()

    • getContext

      public Context getContext()
      Specified by:
      getContext in interface WebResourceRoot
      Returns:
      the web application this WebResourceRoot is associated with.

    • setContext

      public void setContext(Context context)
      Description copied from interface: WebResourceRoot
      Set the web application this WebResourceRoot is associated with.
      Specified by:
      setContext in interface WebResourceRoot
      Parameters:
      context - the associated context

    • processWebInfLib

      protected void processWebInfLib() throws LifecycleException
      Class loader resources are handled by treating JARs in WEB-INF/lib as resource JARs (without the internal META-INF/resources/ prefix) mounted at WEB-INF/classes (rather than the web app root). This enables reuse of the resource handling plumbing. These resources are marked as class loader only so they are only used in the methods that are explicitly defined to return class loader resources. This prevents calls to getResource("/WEB-INF/classes") returning from one or more of the JAR files.
      Throws:
      LifecycleException - If an error occurs that should stop the web application from starting

    • setMainResources

      protected final void setMainResources(WebResourceSet main)
      For unit testing.
      Parameters:
      main - The main resources

    • backgroundProcess

      public void backgroundProcess()
      Description copied from interface: WebResourceRoot
      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.
      Specified by:
      backgroundProcess in interface WebResourceRoot

    • gc

      public void gc()
      Description copied from interface: WebResourceRoot
      Implementations may cache some information to improve performance. This method triggers the clean-up of those resources.
      Specified by:
      gc in interface WebResourceRoot

    • registerTrackedResource

      public void registerTrackedResource(TrackedWebResource trackedResource)
      Description copied from interface: WebResourceRoot
      Add a specified resource to track to be able to later release resources on stop.
      Specified by:
      registerTrackedResource in interface WebResourceRoot
      Parameters:
      trackedResource - the resource that will be tracked

    • deregisterTrackedResource

      public void deregisterTrackedResource(TrackedWebResource trackedResource)
      Description copied from interface: WebResourceRoot
      Stop tracking specified resource, once it no longer needs to free resources.
      Specified by:
      deregisterTrackedResource in interface WebResourceRoot
      Parameters:
      trackedResource - the resource that was tracked

    • getBaseUrls

      public List<URL> getBaseUrls()
      Specified by:
      getBaseUrls in interface WebResourceRoot
      Returns:
      the set of WebResourceSet.getBaseUrl() for all WebResourceSets used by this root.

    • isPackedWarFile

      protected boolean isPackedWarFile()

    • getDomainInternal

      protected String getDomainInternal()
      Description copied from class: LifecycleMBeanBase
      Method implemented by sub-classes to identify the domain in which MBeans should be registered.
      Specified by:
      getDomainInternal in class LifecycleMBeanBase
      Returns:
      The name of the domain to use to register MBeans.

    • getObjectNameKeyProperties

      protected String getObjectNameKeyProperties()
      Description copied from class: LifecycleMBeanBase
      Allow sub-classes to specify the key properties component of the ObjectName that will be used to register this component.
      Specified by:
      getObjectNameKeyProperties in class LifecycleMBeanBase
      Returns:
      The string representation of the key properties component of the desired ObjectName

    • initInternal

      protected void initInternal() throws LifecycleException
      Description copied from class: LifecycleBase
      Sub-classes implement this method to perform any instance initialisation required.
      Overrides:
      initInternal in class LifecycleMBeanBase
      Throws:
      LifecycleException - If the initialisation fails

    • registerURLStreamHandlerFactory

      protected void registerURLStreamHandlerFactory()

    • startInternal

      protected void startInternal() throws LifecycleException
      Description copied from class: LifecycleBase
      Sub-classes must ensure that the state is changed to LifecycleState.STARTING during the execution of this method. Changing state will trigger the Lifecycle.START_EVENT event. If a component fails to start it may either throw a LifecycleException which will cause it's parent to fail to start or it can place itself in the error state in which case LifecycleBase.stop() will be called on the failed component but the parent component will continue to start normally.
      Specified by:
      startInternal in class LifecycleBase
      Throws:
      LifecycleException - Start error occurred

    • createMainResourceSet

      protected WebResourceSet createMainResourceSet()

    • stopInternal

      protected void stopInternal() throws LifecycleException
      Description copied from class: LifecycleBase
      Sub-classes must ensure that the state is changed to LifecycleState.STOPPING during the execution of this method. Changing state will trigger the Lifecycle.STOP_EVENT event.
      Specified by:
      stopInternal in class LifecycleBase
      Throws:
      LifecycleException - Stop error occurred

    • destroyInternal

      protected void destroyInternal() throws LifecycleException
      Description copied from class: LifecycleBase
      Sub-classes implement this method to perform any instance destruction required.
      Overrides:
      destroyInternal in class LifecycleMBeanBase
      Throws:
      LifecycleException - If the destruction fails