Package liquibase.resource

Class AbstractPathResourceAccessor

java.lang.Object
liquibase.AbstractExtensibleObject
liquibase.resource.AbstractResourceAccessor
liquibase.resource.AbstractPathResourceAccessor
All Implemented Interfaces:
AutoCloseable, Cloneable, ExtensibleObject, ResourceAccessor
Direct Known Subclasses:
DirectoryResourceAccessor, ZipResourceAccessor
public abstract class AbstractPathResourceAccessor extends AbstractResourceAccessor
Base class for ResourceAccessors that resolve a caller-supplied path against a configured root directory (file system, zip, etc.).

Containment guarantee (gated by GlobalConfiguration.ALLOW_PARENT_DIRECTORY_REFERENCES). When the flag is false, both getAll(String) and search(String, SearchOptions) reject any path that, after normalisation, escapes the configured getRootPath(). They additionally verify the canonical real path (after symbolic-link resolution) stays within the canonical root, so a symlink located inside the root that targets a file outside it is not silently followed.

When the flag is true (the current default, for one major release as a deprecation window), both checks are skipped — the behaviour matches the pre-CWE-22-fix code path. This preserves legitimate multi-changelog layouts that depend on parent-directory traversal (e.g. <include file="../shared/foo.xml"> or a Pro custom-check SCRIPT_PATH pointing to a sibling directory). A future major release will flip the default to false, at which point callers depending on parent-directory traversal must either restructure their layout or explicitly opt in via the flag.

Caveats (only applicable when the flag is false).

  • The containment check is evaluated at getAll / search time. A symlink created or modified after the check (TOCTOU race) is not re-validated when the returned Resource's stream is opened later.
  • For search(String, SearchOptions), each visited file or directory is re-checked individually so symlinks discovered during the walk are skipped rather than aborting the whole walk.

  • Constructor Details

    • AbstractPathResourceAccessor

      public AbstractPathResourceAccessor()

  • Method Details

    • getRootPath

      protected abstract Path getRootPath()

    • toString

      public String toString()
      Overrides:
      toString in class AbstractExtensibleObject

    • describeLocations

      public List<String> describeLocations()
      Description copied from interface: ResourceAccessor
      Returns a description of the places this classloader will look for paths. Used in error messages and other troubleshooting cases.

    • getAll

      public List<Resource> getAll(String path) throws IOException
      Description copied from interface: ResourceAccessor
      Returns all Resources at the given path. For many resource accessors (such as a file system), only one resource can exist at a given spot, but some accessors (such as CompositeResourceAccessor or ClassLoaderResourceAccessor) can have multiple resources for a single path.

      If the resourceAccessor returns multiple values, the returned List should be considered sorted for that resource accessor. For example, ClassLoaderResourceAccessor returns them in order based on the configured classloader. Order is important to pay attention to, because users may set GlobalConfiguration.DUPLICATE_FILE_MODE to pick the "best" file which is defined as "the first file from this function".

      Returns:
      null if no resources match the path
      Throws:
      IOException - if there is an unexpected error determining what is at the path

    • search

      public List<Resource> search(String startPath, ResourceAccessor.SearchOptions searchOptions) throws IOException
      Description copied from interface: ResourceAccessor
      Returns the path to all resources contained in the given path that match the searchOptions criteria. Multiple resources may be returned with the same path, but only if they are actually unique files. Order is important to pay attention to, they should be returned in a user-expected manner based on this resource accessor.

      Should return an empty list if:
      • Path does not exist or maxDepth less or equals than zero
      Should throw an exception if:
      • Path is null
      • Path is not a "directory"
      • Path exists but cannot be read from
      Parameters:
      startPath - The path to lookup resources in.
      searchOptions - A set of criteria for how resources should be found/filtered
      Returns:
      empty set if nothing was found
      Throws:
      IOException - if there is an error searching the system.

    • search

      public List<Resource> search(String startPath, boolean recursive) throws IOException
      Description copied from interface: ResourceAccessor
      Returns the path to all resources contained in the given path. Multiple resources may be returned with the same path, but only if they are actually unique files. Order is important to pay attention to, they should be returned in a user-expected manner based on this resource accessor.

      Should return an empty list if:
      • Path does not exist
      Should throw an exception if:
      • Path is null
      • Path is not a "directory"
      • Path exists but cannot be read from
      Parameters:
      startPath - The path to lookup resources in.
      recursive - Set to true and will return paths to contents in subdirectories as well.
      Returns:
      empty set if nothing was found
      Throws:
      IOException - if there is an error searching the system.

    • createResource

      protected abstract Resource createResource(Path file, String pathToAdd)