Package org.apache.juneau.commons.io

Class FileReaderBuilder

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

This builder provides a convenient way to create file readers with custom character encodings and optional handling for missing files. It's particularly useful when you need to read files with specific encodings or handle cases where files may not exist.

Features:
  • Fluent API - all methods return this for method chaining
  • Character encoding support - specify custom charset for file reading
  • Missing file handling - optional support for returning empty reader when file doesn't exist
  • Multiple file specification methods - accept File, String path, or Path
Use Cases:
  • Reading files with specific character encodings (UTF-8, ISO-8859-1, etc.)
  • Handling optional configuration files that may not exist
  • Creating readers with consistent encoding across an application
  • Reading files where encoding must be explicitly specified
Usage:

// Basic usage Reader reader = FileReaderBuilder.create() .file("/path/to/file.txt") .charset("UTF-8") .build(); // With missing file handling Reader reader2 = FileReaderBuilder.create() .file("optional-config.properties") .allowNoFile() .build(); // Returns empty StringReader if file doesn't exist // Using File object File f = new File("data.txt"); Reader reader3 = FileReaderBuilder.create(f) .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.

See Also:

  • Constructor Details

  • Method Details

    • create

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

      Reader reader = FileReaderBuilder.create() .file("data.txt") .build();

      Returns:
      A new builder instance.

    • create

      public static FileReaderBuilder create(File file)
      Creates a new builder initialized with the specified file.
      Example:

      File file = new File("config.properties"); Reader reader = FileReaderBuilder.create(file) .charset("UTF-8") .build();

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

    • allowNoFile

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

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

      Example:

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

      Returns:
      This object for method chaining.

    • build

      public Reader build() throws FileNotFoundException
      Creates a new Reader for reading from the configured file.

      If allowNoFile() was called and the file is null or does not exist, this method returns an empty StringReader. Otherwise, it creates an InputStreamReader with the specified character encoding.

      Example:

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

      Returns:
      A new Reader for reading from the file.
      Throws:
      FileNotFoundException - If the file could not be found and allowNoFile() was not called.

    • charset

      public FileReaderBuilder charset(Charset cs)
      Sets the character encoding for reading the file.

      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.

      Example:

      Reader reader = FileReaderBuilder.create() .file("data.txt") .charset(StandardCharsets.UTF_8) .build();

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

    • charset

      public FileReaderBuilder charset(String cs)
      Sets the character encoding for reading the file by charset name.

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

      Example:

      Reader reader = FileReaderBuilder.create() .file("data.txt") .charset("UTF-8") .build();

      Parameters:
      cs - The character encoding name (e.g., "UTF-8", "ISO-8859-1"). The default is Charset.defaultCharset(). Must not be null.
      Returns:
      This object for method chaining.

    • file

      public FileReaderBuilder file(File value)
      Sets the file to read from.
      Example:

      File f = new File("config.properties"); Reader reader = FileReaderBuilder.create() .file(f) .build();

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

    • file

      public FileReaderBuilder file(String path)
      Sets the file path to read from.
      Example:

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

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