Package org.apache.juneau.commons.io

Class PathReaderBuilder

java.lang.Object
org.apache.juneau.commons.io.PathReaderBuilder
public class PathReaderBuilder extends Object
A fluent builder for creating Reader instances from Path objects with configurable character encoding.

This builder provides a convenient way to create readers from NIO Path objects with custom character encodings and optional handling for missing files. It's similar to FileReaderBuilder but works with the modern NIO Path API instead of the legacy File API.

Features:
  • Fluent API - all methods return this for method chaining
  • NIO Path support - works with modern Path API
  • Character encoding support - specify custom charset for file reading
  • Missing file handling - optional support for returning empty reader when file doesn't exist
  • Multiple path specification methods - accept Path or String path
Use Cases:
  • Reading files with specific character encodings using NIO Path API
  • Handling optional configuration files that may not exist
  • Creating readers with consistent encoding across an application
  • Working with NIO-based file operations
Usage:

// Basic usage Reader reader = PathReaderBuilder.create() .path(Paths.get("/path/to/file.txt")) .charset("UTF-8") .build(); // With missing file handling Reader reader2 = PathReaderBuilder.create() .path("optional-config.properties") .allowNoFile() .build(); // Returns empty StringReader if file doesn't exist // Using Path object Path path = Paths.get("data.txt"); Reader reader3 = PathReaderBuilder.create(path) .charset(StandardCharsets.UTF_8) .build();

Character Encoding:

By default, the builder uses the system's default charset (Charset.defaultCharset()). You can specify a custom charset using charset(Charset) or charset(String). This is important when reading files that were written with a specific encoding.

Comparison with FileReaderBuilder:
See Also:
Since:
9.1.0

  • Constructor Details

  • Method Details

    • create

      public static PathReaderBuilder create()
      Creates a new builder.
      Example:

      Reader reader = PathReaderBuilder.create() .path(Paths.get("data.txt")) .build();

      Returns:
      A new builder instance.

    • create

      public static PathReaderBuilder create(Path path)
      Creates a new builder initialized with the specified path.
      Example:

      Path path = Paths.get("config.properties"); Reader reader = PathReaderBuilder.create(path) .charset("UTF-8") .build();

      Parameters:
      path - The path to read from.
      Returns:
      A new builder instance initialized with the specified path.

    • allowNoFile

      public PathReaderBuilder allowNoFile()
      Enables handling of missing files by returning an empty reader instead of throwing an exception.

      When this option is enabled, if the path is null or does not exist, the build() method will return a StringReader with empty content instead of throwing an IOException. This is useful for optional configuration files.

      Example:

      // Without allowNoFile - throws exception if file doesn't exist Reader reader1 = PathReaderBuilder.create() .path(Paths.get("required.txt")) .build(); // Throws NoSuchFileException if file missing // With allowNoFile - returns empty reader if file doesn't exist Reader reader2 = PathReaderBuilder.create() .path(Paths.get("optional.txt")) .allowNoFile() .build(); // Returns empty StringReader if file missing

      Returns:
      This object for method chaining.

    • build

      public Reader build() throws IOException
      Creates a new Reader for reading from the configured path.

      If allowNoFile() was called and the path is null or does not exist, this method returns an empty StringReader. Otherwise, it creates a buffered reader using Files.newBufferedReader(Path, Charset) with the specified character encoding.

      Example:

      try (Reader reader = PathReaderBuilder.create() .path(Paths.get("data.txt")) .charset("UTF-8") .build()) { // Read from file }

      Returns:
      A new Reader for reading from the path.
      Throws:
      IllegalStateException - If no path is configured and allowNoFile() was not called.
      NoSuchFileException - If the path does not exist and allowNoFile() was not called.
      IOException - If an I/O error occurs opening the path.

    • charset

      public PathReaderBuilder charset(Charset charset)
      Sets the character encoding for reading the path.

      If not specified, the system's default charset (Charset.defaultCharset()) is used. Specifying the encoding is important when reading files that were written with a specific character encoding. Passing null resets to the default charset.

      Example:

      Reader reader = PathReaderBuilder.create() .path(Paths.get("data.txt")) .charset(StandardCharsets.UTF_8) .build();

      Parameters:
      charset - The character encoding to use. The default is Charset.defaultCharset(). null resets to the default.
      Returns:
      This object for method chaining.

    • charset

      public PathReaderBuilder charset(String charset)
      Sets the character encoding for reading the path by charset name.

      This is a convenience method that accepts a charset name string and converts it to a Charset using Charset.forName(String). Passing null resets to the default charset.

      Example:

      Reader reader = PathReaderBuilder.create() .path(Paths.get("data.txt")) .charset("UTF-8") .build();

      Parameters:
      charset - The character encoding name (e.g., "UTF-8", "ISO-8859-1"). The default is Charset.defaultCharset(). null resets to the default.
      Returns:
      This object for method chaining.

    • path

      public PathReaderBuilder path(Path path)
      Sets the path to read from.
      Example:

      Path p = Paths.get("config.properties"); Reader reader = PathReaderBuilder.create() .path(p) .build();

      Parameters:
      path - The path to read from.
      Returns:
      This object for method chaining.

    • path

      public PathReaderBuilder path(String path)
      Sets the path to read from by string path.

      This is a convenience method that converts a string path to a Path using Paths.get(String, String...).

      Example:

      Reader reader = PathReaderBuilder.create() .path("/path/to/file.txt") .build();

      Parameters:
      path - The file path to read from. Must not be null.
      Returns:
      This object for method chaining.