Package org.apache.juneau.commons.io

Class FileWriterBuilder

java.lang.Object
org.apache.juneau.commons.io.FileWriterBuilder
public class FileWriterBuilder extends Object
A fluent builder for creating Writer instances for writing to files with configurable options.

This builder provides a convenient way to create file writers with custom character encodings, append mode, and buffering options. It's particularly useful when you need to write files with specific encodings or control whether to append to existing files.

Features:
  • Fluent API - all methods return this for method chaining
  • Character encoding support - specify custom charset for file writing
  • Append mode - optionally append to existing files instead of overwriting
  • Buffering support - optional buffering for improved performance
  • Multiple file specification methods - accept File or String path
Use Cases:
  • Writing files with specific character encodings (UTF-8, ISO-8859-1, etc.)
  • Appending to log files or data files
  • Creating writers with consistent encoding across an application
  • Writing files where buffering improves performance
Usage:

// Basic usage Writer writer = FileWriterBuilder.create() .file("/path/to/file.txt") .charset("UTF-8") .build(); // Append mode Writer logWriter = FileWriterBuilder.create() .file("app.log") .append() .build(); // With buffering Writer bufferedWriter = FileWriterBuilder.create() .file("output.txt") .buffered() .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 writing files that need to be read with a specific encoding.

See Also:

  • Constructor Details

  • Method Details

    • create

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

      Writer writer = FileWriterBuilder.create() .file("output.txt") .build();

      Returns:
      A new builder instance.

    • create

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

      File file = new File("output.txt"); Writer writer = FileWriterBuilder.create(file) .charset("UTF-8") .build();

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

    • create

      public static FileWriterBuilder create(String path)
      Creates a new builder initialized with the specified file path.
      Example:

      Writer writer = FileWriterBuilder.create("/path/to/output.txt") .append() .build();

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

    • append

      public FileWriterBuilder append()
      Enables append mode, which appends to the file instead of overwriting it.

      When append mode is enabled, data written to the file will be appended to the end of the existing file content rather than overwriting it. This is useful for log files or data files where you want to preserve existing content.

      Example:

      // Append to log file Writer logWriter = FileWriterBuilder.create() .file("app.log") .append() .build(); logWriter.write("New log entry\n"); // Appends to existing content

      Returns:
      This object for method chaining.

    • buffered

      public FileWriterBuilder buffered()
      Enables buffering for improved write performance.

      When buffering is enabled, the writer wraps the underlying output stream with a BufferedOutputStream, which can significantly improve performance for multiple small writes by batching them together.

      Example:

      // Buffered writer for better performance Writer writer = FileWriterBuilder.create() .file("output.txt") .buffered() .build();

      Returns:
      This object for method chaining.

    • build

      public Writer build() throws FileNotFoundException
      Creates a new Writer for writing to the configured file.

      The writer is created with the specified character encoding, append mode, and buffering options. The file will be created if it doesn't exist (unless in append mode, where the file must exist or be creatable).

      Example:

      try (Writer writer = FileWriterBuilder.create() .file("output.txt") .charset("UTF-8") .buffered() .build()) { writer.write("Hello World"); }

      Returns:
      A new Writer for writing to the file.
      Throws:
      FileNotFoundException - If the file could not be created or opened for writing.

    • charset

      public FileWriterBuilder charset(Charset cs)
      Sets the character encoding for writing to the file.

      If not specified, the system's default charset (Charset.defaultCharset()) is used. Specifying the encoding is important when writing files that need to be read with a specific character encoding.

      Example:

      Writer writer = FileWriterBuilder.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 FileWriterBuilder charset(String cs)
      Sets the character encoding for writing to 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:

      Writer writer = FileWriterBuilder.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 FileWriterBuilder file(File value)
      Sets the file to write to.
      Example:

      File f = new File("output.txt"); Writer writer = FileWriterBuilder.create() .file(f) .build();

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

    • file

      public FileWriterBuilder file(String path)
      Sets the file path to write to.
      Example:

      Writer writer = FileWriterBuilder.create() .file("/path/to/output.txt") .build();

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