DirResourceSet (Apache Tomcat 11.0.23 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 Lifecycle

  `Lifecycle.SingleUse`

  ### Nested classes/interfaces inherited from interface WebResourceLockSet

  `WebResourceLockSet.ResourceLock`

- ## Field Summary

  ### Fields inherited from class AbstractFileResourceSet

  `EMPTY_STRING_ARRAY`

  ### Fields inherited from class AbstractResourceSet

  `sm`

  ### Fields inherited from interface 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)`
  Checks the type of the specified file.
  `ReadWriteLock`
  `getLock(String path)`
  Obtain a reentrant read/write lock for the resource at the provided path.
  `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 AbstractFileResourceSet

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

  ### Methods inherited from class AbstractResourceSet

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

  ### Methods inherited from class LifecycleBase

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

  ### Methods inherited from class Object

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

  ### Methods inherited from interface 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)
    Description copied from class: `AbstractFileResourceSet`
    Checks the type of the specified file.
    Specified by:
      `checkType` in class `AbstractFileResourceSet`
    Parameters:
      `file` - The file to check

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

  - ### getLock

    public ReadWriteLock getLock(String path)
    Description copied from interface: `WebResourceLockSet`
    Obtain a reentrant read/write lock for the resource at the provided path. The resource is not required to exist. Multiple calls to this method with the same path will return the same lock provided that at least one instance of the lock remains in use between the calls.
    Specified by:
      `getLock` in interface `WebResourceLockSet`
    Parameters:
      `path` - The path for which the lock should be obtained
    Returns:
      A reentrant read/write lock for the given resource.

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