Package org.apache.juneau.commons.io

Class LocalDir

java.lang.Object
org.apache.juneau.commons.io.LocalDir
public class LocalDir extends Object
Represents a directory that can be located either on the classpath or in the file system.

This class provides a unified interface for working with directories regardless of their location, allowing code to transparently access files within directories from either the classpath (as resources) or the file system. This is particularly useful in applications that need to work with directory-based resources in both development (file system) and production (packaged JAR) environments.

Features:
  • Unified directory access - works with both classpath resources and file system directories
  • File resolution - can resolve files within the directory using relative paths
  • Transparent resolution - automatically resolves files based on construction parameters
  • Immutable - directory location cannot be changed after construction
Use Cases:
  • Accessing template directories that may be on classpath or file system
  • Loading configuration files from directories in both development and production
  • Resolving resources within package directories
  • Applications that need to support both embedded and external directory access
Usage:

// Classpath directory LocalDir classpathDir = new LocalDir(MyClass.class, "templates"); LocalFile file = classpathDir.resolve("index.html"); // File system directory LocalDir fsDir = new LocalDir(Paths.get("/var/config")); LocalFile file2 = fsDir.resolve("app.properties"); // Package directory (null or empty path) LocalDir packageDir = new LocalDir(MyClass.class, null); LocalFile file3 = packageDir.resolve("resource.txt");

Path Resolution:

The resolve(String) method resolves files within the directory using relative paths. For classpath directories, the path resolution follows Java resource path conventions:

  • null or empty string - resolves relative to the class's package
  • Absolute path (starts with '/') - resolves relative to classpath root
  • Relative path - resolves relative to the specified classpath path
Thread Safety:

This class is immutable and therefore thread-safe. Multiple threads can safely access a LocalDir instance concurrently without synchronization.

See Also:

  • Constructor Details

    • LocalDir

      public LocalDir(Class<?> clazz, String clazzPath)
      Constructor for classpath directory.

      Creates a LocalDir that references a directory on the classpath, relative to the specified class. The path resolution follows Java resource path conventions.

      Path Examples:

      // Package directory (null or empty) LocalDir dir1 = new LocalDir(MyClass.class, null); // Resolves files in same package as MyClass // Absolute path from classpath root LocalDir dir2 = new LocalDir(MyClass.class, "/com/example/templates"); // Resolves files from classpath root // Relative path from class package LocalDir dir3 = new LocalDir(MyClass.class, "templates"); // Resolves files relative to MyClass package

      Parameters:
      clazz - The class used to retrieve resources. Must not be null.
      clazzPath - The subpath. Can be any of the following:
      • null or an empty string - Package of the class
      • Absolute path (starts with '/') - Relative to root package
      • Relative path (does not start with '/') - Relative to class package

    • LocalDir

      public LocalDir(Path path)
      Constructor for file system directory.

      Creates a LocalDir that references a directory on the file system using a Path.

      Example:

      // Absolute path LocalDir dir1 = new LocalDir(Paths.get("/var/config")); // Relative path LocalDir dir2 = new LocalDir(Paths.get("data/templates")); // From File object File f = new File("output"); LocalDir dir3 = new LocalDir(f.toPath());

      Parameters:
      path - Filesystem directory location. Must not be null.

  • Method Details

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • resolve

      public LocalFile resolve(String path)
      Resolves a file within this directory using the specified relative path.

      This method attempts to locate a file within the directory. If the file exists and is readable, a LocalFile instance is returned. If the file does not exist or is not accessible, null is returned.

      For classpath directories, the path is resolved according to the directory's path type:

      • Package directory (null clazzPath) - path is kept relative
      • Root directory ("/") - path is made absolute if not already
      • Absolute clazzPath - resolved path is made absolute
      • Relative clazzPath - resolved path remains relative
      Example:

      LocalDir dir = new LocalDir(MyClass.class, "templates"); // Resolve file in directory LocalFile file = dir.resolve("index.html"); if (file != null) { InputStream is = file.read(); } // Resolve file in subdirectory LocalFile file2 = dir.resolve("pages/about.html");

      Security Note:

      This method does not perform path validation or security checks (e.g., checking for path traversal attacks or malformed values). The caller is responsible for ensuring the path is safe and valid.

      Parameters:
      path - The relative path to the file to resolve within this directory. Must be a non-null relative path.
      Returns:
      A LocalFile instance if the file exists and is readable, or null if it does not.

    • toString

      public String toString()
      Overrides:
      toString in class Object