DirResourceSet (Apache Tomcat 11.0.8 API Documentation)
Description: declaration: package: org.apache.catalina.webresources, class: DirResourceSet

# Class DirResourceSet

java.lang.Object
org.apache.catalina.util.LifecycleBase
org.apache.catalina.webresources.AbstractResourceSet
org.apache.catalina.webresources.AbstractFileResourceSet
org.apache.catalina.webresources.DirResourceSet

All Implemented Interfaces:
  `Lifecycle`, `WebResourceLockSet`, `WebResourceSet`

public class DirResourceSet extends AbstractFileResourceSet implements WebResourceLockSet
Represents a `WebResourceSet` based on a directory.

- ## Nested Class Summary

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

  `Lifecycle.SingleUse`

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

  `WebResourceLockSet.ResourceLock`

- ## Field Summary

  ### Fields inherited from class org.apache.catalina.webresources.AbstractFileResourceSet

  `EMPTY_STRING_ARRAY`

  ### Fields inherited from class org.apache.catalina.webresources.AbstractResourceSet

  `sm`

  ### 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`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DirResourceSet()`
  A no argument constructor is required for this to work with the digester.
  `DirResourceSet(WebResourceRoot root, String webAppMount, String base, String internalPath)`
  Creates a new `WebResourceSet` based on a directory.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `checkType(File file)`
  `WebResource`
  `getResource(String path)`
  Obtain the object that represents the resource at the given path.
  `protected void`
  `initInternal()`
  Subclasses implement this method to perform any instance initialisation required.
  `String[]`
  `list(String path)`
  Obtain the list of the names of all of the files and directories located 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.
  `WebResourceLockSet.ResourceLock`
  `lockForRead(String path)`
  Lock the resource at the provided path for reading.
  `WebResourceLockSet.ResourceLock`
  `lockForWrite(String path)`
  Lock the resource at the provided path for writing.
  `boolean`
  `mkdir(String path)`
  Create a new directory at the given path.
  `void`
  `unlockForRead(WebResourceLockSet.ResourceLock resourceLock)`
  Release a read lock from the resource associated with the given `WebResourceLockSet.ResourceLock`.
  `void`
  `unlockForWrite(WebResourceLockSet.ResourceLock resourceLock)`
  Release the write lock from the resource associated with the given `WebResourceLockSet.ResourceLock`.
  `boolean`
  `write(String path, InputStream is, boolean overwrite)`
  Create a new resource at the requested path using the provided InputStream.

  ### Methods inherited from class org.apache.catalina.webresources.AbstractFileResourceSet

  `file, gc, getAllowLinking, getBaseUrl, getFileBase, isReadOnly, logIgnoredSymlink, setAllowLinking, setReadOnly`

  ### Methods inherited from class org.apache.catalina.webresources.AbstractResourceSet

  `checkPath, destroyInternal, getBase, getClassLoaderOnly, getInternalPath, getManifest, getRoot, getStaticOnly, getWebAppMount, isPathMounted, setBase, setClassLoaderOnly, setInternalPath, setManifest, setRoot, setStaticOnly, setWebAppMount, startInternal, stopInternal`

  ### Methods inherited from class org.apache.catalina.util.LifecycleBase

  `addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

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

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

- ## Constructor Details

  - ### DirResourceSet

    public DirResourceSet()
    A no argument constructor is required for this to work with the digester.

  - ### DirResourceSet

    public DirResourceSet(WebResourceRoot root, String webAppMount, String base, String internalPath)
    Creates a new `WebResourceSet` based on a directory.
    Parameters:
      `root` - The `WebResourceRoot` this new `WebResourceSet` will be added to.
      `webAppMount` - The path within the web application at which this `WebResourceSet` will be mounted. For example, to add a directory of JARs to a web application, the directory would be mounted at "/WEB-INF/lib/"
      `base` - The absolute path to the directory on the file system from which the resources will be served.
      `internalPath` - The path within this new `WebResourceSet` where resources will be served from.

- ## Method Details

  - ### getResource

    public WebResource getResource(String path)
    Description copied from interface: `WebResourceSet`
    Obtain the object that represents the resource at the given path. Note the resource at that path may not exist.
    Specified by:
      `getResource` in interface `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

  - ### list

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

  - ### mkdir

    public boolean mkdir(String path)
    Description copied from interface: `WebResourceSet`
    Create a new directory at the given path.
    Specified by:
      `mkdir` in interface `WebResourceSet`
    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: `WebResourceSet`
    Create a new resource at the requested path using the provided InputStream.
    Specified by:
      `write` in interface `WebResourceSet`
    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

  - ### checkType

    protected void checkType(File file)
    Specified by:
      `checkType` in class `AbstractFileResourceSet`

  - ### initInternal

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

  - ### lockForRead

    public WebResourceLockSet.ResourceLock lockForRead(String path)
    Description copied from interface: `WebResourceLockSet`
    Lock the resource at the provided path for reading. The resource is not required to exist. Read locks are not exclusive.
    Specified by:
      `lockForRead` in interface `WebResourceLockSet`
    Parameters:
      `path` - The path to the resource to be locked for reading
    Returns:
      The `WebResourceLockSet.ResourceLock` that must be passed to `WebResourceLockSet.unlockForRead(ResourceLock)` to release the lock

  - ### unlockForRead

    public void unlockForRead(WebResourceLockSet.ResourceLock resourceLock)
    Description copied from interface: `WebResourceLockSet`
    Release a read lock from the resource associated with the given `WebResourceLockSet.ResourceLock`.
    Specified by:
      `unlockForRead` in interface `WebResourceLockSet`
    Parameters:
      `resourceLock` - The `WebResourceLockSet.ResourceLock` associated with the resource for which a read lock should be released

  - ### lockForWrite

    public WebResourceLockSet.ResourceLock lockForWrite(String path)
    Description copied from interface: `WebResourceLockSet`
    Lock the resource at the provided path for writing. The resource is not required to exist. Write locks are exclusive.
    Specified by:
      `lockForWrite` in interface `WebResourceLockSet`
    Parameters:
      `path` - The path to the resource to be locked for writing
    Returns:
      The `WebResourceLockSet.ResourceLock` that must be passed to `WebResourceLockSet.unlockForWrite(ResourceLock)` to release the lock

  - ### unlockForWrite

    public void unlockForWrite(WebResourceLockSet.ResourceLock resourceLock)
    Description copied from interface: `WebResourceLockSet`
    Release the write lock from the resource associated with the given `WebResourceLockSet.ResourceLock`.
    Specified by:
      `unlockForWrite` in interface `WebResourceLockSet`
    Parameters:
      `resourceLock` - The `WebResourceLockSet.ResourceLock` associated with the resource for which the write lock should be released