Package org.apache.commons.io.output

# Class LockableFileWriter

java.lang.Object
java.io.Writer
org.apache.commons.io.output.LockableFileWriter

All Implemented Interfaces:
  `Closeable`, `Flushable`, `Appendable`, `AutoCloseable`

public class LockableFileWriter extends Writer
FileWriter that will create and honor lock files to allow simple cross thread file lock handling.

This class provides a simple alternative to `FileWriter` that will use a lock file to prevent duplicate writes.

Note: The lock file is deleted when `close()` is called - or if the main file cannot be opened initially. In the (unlikely) event that the lock file cannot be deleted, an exception is thrown.

By default, the file will be overwritten, but this may be changed to append. The lock directory may be specified, but defaults to the system property `java.io.tmpdir`. The encoding may also be specified, and defaults to the platform default.

To build an instance, use `LockableFileWriter.Builder`.

See Also:
  - `LockableFileWriter.Builder`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `LockableFileWriter.Builder`
  Builds a new `LockableFileWriter`.

- ## Field Summary

  ### Fields inherited from class java.io.Writer

  `lock`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LockableFileWriter(File file)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
  `LockableFileWriter(File file, boolean append)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
  `LockableFileWriter(File file, boolean append, String lockDir)`
  Deprecated.
  Use `LockableFileWriter(File, Charset, boolean, String)` instead.
  `LockableFileWriter(File file, String charsetName)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
  `LockableFileWriter(File file, String charsetName, boolean append, String lockDir)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
  `LockableFileWriter(File file, Charset charset)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
  `LockableFileWriter(File file, Charset charset, boolean append, String lockDir)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
  `LockableFileWriter(String fileName)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
  `LockableFileWriter(String fileName, boolean append)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
  `LockableFileWriter(String fileName, boolean append, String lockDir)`
  Deprecated.
  Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static LockableFileWriter.Builder`
  `builder()`
  Constructs a new `LockableFileWriter.Builder`.
  `void`
  `close()`
  Closes the file writer and deletes the lock file.
  `void`
  `flush()`
  Flushes the stream.
  `void`
  `write(char[] cbuf)`
  Writes the characters from an array.
  `void`
  `write(char[] cbuf, int off, int len)`
  Writes the specified characters from an array.
  `void`
  `write(int c)`
  Writes a character.
  `void`
  `write(String str)`
  Writes the characters from a string.
  `void`
  `write(String str, int off, int len)`
  Writes the specified characters from a string.

  ### Methods inherited from class java.io.Writer

  `append, append, append`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(File file) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter. If the file exists, it is overwritten.
    Parameters:
      `file` - the file to write to, not null.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(File file, boolean append) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter.
    Parameters:
      `file` - the file to write to, not null.
      `append` - true if content should be appended, false to overwrite.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(File file, boolean append, String lockDir) throws IOException
    Deprecated.
    Use `LockableFileWriter(File, Charset, boolean, String)` instead.
    Constructs a LockableFileWriter.

    The new instance uses the virtual machine's default charset.

    Parameters:
      `file` - the file to write to, not null.
      `append` - true if content should be appended, false to overwrite.
      `lockDir` - the directory in which the lock file should be held.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(File file, Charset charset) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter with a file encoding.
    Parameters:
      `file` - the file to write to, not null.
      `charset` - the charset to use, null means platform default.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.
    Since:
      2.3

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(File file, Charset charset, boolean append, String lockDir) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter with a file encoding.
    Parameters:
      `file` - the file to write to, not null.
      `charset` - the name of the requested charset, null means platform default.
      `append` - true if content should be appended, false to overwrite.
      `lockDir` - the directory in which the lock file should be held.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.
    Since:
      2.3

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(File file, String charsetName) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter with a file encoding.
    Parameters:
      `file` - the file to write to, not null.
      `charsetName` - the name of the requested charset, null means platform default.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.
      `UnsupportedCharsetException` - thrown instead of `UnsupportedEncodingException` in version 2.2 if the encoding is not supported.

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(File file, String charsetName, boolean append, String lockDir) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter with a file encoding.
    Parameters:
      `file` - the file to write to, not null.
      `charsetName` - the encoding to use, null means platform default.
      `append` - true if content should be appended, false to overwrite.
      `lockDir` - the directory in which the lock file should be held.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.
      `UnsupportedCharsetException` - thrown instead of `UnsupportedEncodingException` in version 2.2 if the encoding is not supported.

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(String fileName) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter. If the file exists, it is overwritten.
    Parameters:
      `fileName` - the file to write to, not null.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(String fileName, boolean append) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter.
    Parameters:
      `fileName` - file to write to, not null.
      `append` - true if content should be appended, false to overwrite.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.

  - ### LockableFileWriter

    @Deprecated public LockableFileWriter(String fileName, boolean append, String lockDir) throws IOException
    Deprecated.
    Use `builder()`, `LockableFileWriter.Builder`, and `LockableFileWriter.Builder.get()`.
    Constructs a LockableFileWriter.
    Parameters:
      `fileName` - the file to write to, not null.
      `append` - true if content should be appended, false to overwrite.
      `lockDir` - the directory in which the lock file should be held.
    Throws:
      `NullPointerException` - if the file is null.
      `IOException` - in case of an I/O error.

- ## Method Details

  - ### builder

    public static LockableFileWriter.Builder builder()
    Constructs a new `LockableFileWriter.Builder`.
    Returns:
      a new `LockableFileWriter.Builder`.
    Since:
      2.12.0

  - ### close

    public void close() throws IOException
    Closes the file writer and deletes the lock file.
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Specified by:
      `close` in class `Writer`
    Throws:
      `IOException` - if an I/O error occurs.

  - ### flush

    public void flush() throws IOException
    Flushes the stream.
    Specified by:
      `flush` in interface `Flushable`
    Specified by:
      `flush` in class `Writer`
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(char[] cbuf) throws IOException
    Writes the characters from an array.
    Overrides:
      `write` in class `Writer`
    Parameters:
      `cbuf` - the characters to write.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(char[] cbuf, int off, int len) throws IOException
    Writes the specified characters from an array.
    Specified by:
      `write` in class `Writer`
    Parameters:
      `cbuf` - the characters to write.
      `off` - The start offset.
      `len` - The number of characters to write.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(int c) throws IOException
    Writes a character.
    Overrides:
      `write` in class `Writer`
    Parameters:
      `c` - the character to write.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(String str) throws IOException
    Writes the characters from a string.
    Overrides:
      `write` in class `Writer`
    Parameters:
      `str` - the string to write.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(String str, int off, int len) throws IOException
    Writes the specified characters from a string.
    Overrides:
      `write` in class `Writer`
    Parameters:
      `str` - the string to write.
      `off` - The start offset.
      `len` - The number of characters to write.
    Throws:
      `IOException` - if an I/O error occurs.