Package org.apache.juneau.commons.io

Class LocalFile

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

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

Features:
  • Unified file access - works with both classpath resources and file system files
  • Optional caching - can cache file contents in memory for fast repeated access
  • Transparent resolution - automatically resolves files based on construction parameters
  • Thread-safe reading - synchronized access for cached content
Use Cases:
  • Reading configuration files that may be on classpath or file system
  • Accessing template files in both development and production environments
  • Loading resources that need to work in both JAR and unpackaged scenarios
  • Applications that need to support both embedded and external file access
Usage:

// Classpath file LocalFile classpathFile = new LocalFile(MyClass.class, "config.properties"); InputStream is = classpathFile.read(); // File system file LocalFile fsFile = new LocalFile(Paths.get("/path/to/file.txt")); InputStream is2 = fsFile.read(); // With caching for repeated access LocalFile cachedFile = new LocalFile(MyClass.class, "template.html"); cachedFile.cache(); // Cache contents in memory InputStream is3 = cachedFile.read(); // Fast - uses cache

Caching:

The cache() method loads the entire file contents into memory, which can improve performance for files that are accessed multiple times. Once cached, subsequent calls to read() return a ByteArrayInputStream backed by the cached data. Caching is thread-safe and synchronized.

Thread Safety:

This class is thread-safe for reading operations. The caching mechanism uses synchronization to ensure thread-safe access to cached content. Multiple threads can safely call read() concurrently.

See Also:

  • Constructor Details

    • LocalFile

      public LocalFile(Class<?> clazz, String clazzPath)
      Constructor for classpath file.

      Creates a LocalFile that references a file on the classpath, relative to the specified class. The path is resolved using Class.getResourceAsStream(String).

      Example:

      // File in same package as MyClass LocalFile file1 = new LocalFile(MyClass.class, "config.properties"); // File in subdirectory LocalFile file2 = new LocalFile(MyClass.class, "templates/index.html"); // Absolute path from classpath root LocalFile file3 = new LocalFile(MyClass.class, "/com/example/config.xml");

      Parameters:
      clazz - The class used to retrieve resources. Must not be null.
      clazzPath - The path relative to the class. Must be a non-null normalized relative path. Use absolute paths (starting with '/') to reference from classpath root.

    • LocalFile

      public LocalFile(Path path)
      Constructor for file system file.

      Creates a LocalFile that references a file on the file system using a Path. The path must point to an actual file (not a directory) and must have a filename component.

      Example:

      // Absolute path LocalFile file1 = new LocalFile(Paths.get("/etc/config.properties")); // Relative path LocalFile file2 = new LocalFile(Paths.get("data/input.txt")); // From File object File f = new File("output.log"); LocalFile file3 = new LocalFile(f.toPath());

      Parameters:
      path - Filesystem file location. Must not be null. Must not be a root path (must have a filename).
      Throws:
      IllegalArgumentException - if the path is a root path (has no filename).

  • Method Details

    • cache

      public LocalFile cache() throws IOException
      Caches the contents of this file into an internal byte array for quick future retrieval.

      This method reads the entire file into memory and stores it in a byte array. Subsequent calls to read() will return a ByteArrayInputStream backed by this cached data, avoiding repeated file I/O operations. This is useful for files that are accessed multiple times.

      The caching operation is thread-safe and synchronized. If multiple threads call this method concurrently, only one will perform the actual read operation.

      Example:

      LocalFile file = new LocalFile(MyClass.class, "template.html"); file.cache(); // Load into memory // Multiple reads are fast - no I/O InputStream is1 = file.read(); InputStream is2 = file.read();

      Memory Considerations:
      • The entire file is loaded into memory, so use with caution for large files
      • Once cached, the file contents remain in memory for the lifetime of the LocalFile object
      • Cache is shared across all threads accessing this LocalFile instance
      Returns:
      This object for method chaining.
      Throws:
      IOException - If the file could not be read or does not exist.

    • getName

      public String getName()
      Returns the name of this file (filename without directory path).

      For classpath files, this is the last component of the classpath path. For file system files, this is the filename component of the path.

      Example:

      LocalFile file1 = new LocalFile(MyClass.class, "templates/index.html"); String name1 = file1.getName(); // Returns "index.html" LocalFile file2 = new LocalFile(Paths.get("/var/log/app.log")); String name2 = file2.getName(); // Returns "app.log"

      Returns:
      The name of this file (filename component only).

    • read

      public InputStream read() throws IOException
      Returns an input stream for reading the contents of this file.

      If the file has been cached via cache(), this method returns a ByteArrayInputStream backed by the cached data. Otherwise, it returns a new input stream that reads directly from the file (classpath resource or file system).

      Each call to this method returns a new input stream. The caller is responsible for closing the returned stream.

      Example:

      LocalFile file = new LocalFile(MyClass.class, "data.txt"); // Read file contents try (InputStream is = file.read()) { // Process stream }

      Returns:
      An input stream for reading the contents of this file.
      Throws:
      IOException - If the file could not be read, does not exist, or is not accessible.

    • size

      public long size() throws IOException
      Returns the size of this file in bytes.

      For file system files, this method returns the actual file size using Files.size(Path). For classpath files, the size cannot be determined and this method returns -1.

      Example:

      LocalFile fsFile = new LocalFile(Paths.get("/var/log/app.log")); long size = fsFile.size(); // Returns actual file size LocalFile cpFile = new LocalFile(MyClass.class, "resource.txt"); long size2 = cpFile.size(); // Returns -1 (unknown)

      Returns:
      The size of this file in bytes, or -1 if the size cannot be determined (e.g., for classpath resources).
      Throws:
      IOException - If the file size could not be determined (for file system files).