LockableFileWriter (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io.output

## Class LockableFileWriter

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

- All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.Appendable, java.lang.AutoCloseable

      public class LockableFileWriter
      extends java.io.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.

  N.B. the lock file is deleted when `close()` is called - or if the main file cannot be opened initially. In the (unlikely) event that the lockfile cannot be deleted, this is not reported, and subsequent requests using the same lockfile will fail.

  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.

  Version:
    $Id: LockableFileWriter.java 1686747 2015-06-21 18:44:49Z krosenvold $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static java.lang.String` | `LCK` The extension for the lock file.
    `private java.io.File` | `lockFile` The lock file.
    `private java.io.Writer` | `out` The writer to decorate.

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

      `lock`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LockableFileWriter(java.io.File file)` Constructs a LockableFileWriter.
    `LockableFileWriter(java.io.File file, boolean append)` Constructs a LockableFileWriter.
    `LockableFileWriter(java.io.File file, boolean append, java.lang.String lockDir)` Deprecated. 2.5 use `LockableFileWriter(File, Charset, boolean, String)` instead
    `LockableFileWriter(java.io.File file, java.nio.charset.Charset encoding)` Constructs a LockableFileWriter with a file encoding.
    `LockableFileWriter(java.io.File file, java.nio.charset.Charset encoding, boolean append, java.lang.String lockDir)` Constructs a LockableFileWriter with a file encoding.
    `LockableFileWriter(java.io.File file, java.lang.String encoding)` Constructs a LockableFileWriter with a file encoding.
    `LockableFileWriter(java.io.File file, java.lang.String encoding, boolean append, java.lang.String lockDir)` Constructs a LockableFileWriter with a file encoding.
    `LockableFileWriter(java.lang.String fileName)` Constructs a LockableFileWriter.
    `LockableFileWriter(java.lang.String fileName, boolean append)` Constructs a LockableFileWriter.
    `LockableFileWriter(java.lang.String fileName, boolean append, java.lang.String lockDir)` Constructs a LockableFileWriter.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Closes the file writer and deletes the lockfile (if possible).
    `private void` | `createLock()` Creates the lock file.
    `void` | `flush()` Flush the stream.
    `private java.io.Writer` | `initWriter(java.io.File file, java.nio.charset.Charset encoding, boolean append)` Initialise the wrapped file writer.
    `private void` | `testLockDir(java.io.File lockDir)` Tests that we can write to the lock directory.
    `void` | `write(char[] chr)` Write the characters from an array.
    `void` | `write(char[] chr, int st, int end)` Write the specified characters from an array.
    `void` | `write(int idx)` Write a character.
    `void` | `write(java.lang.String str)` Write the characters from a string.
    `void` | `write(java.lang.String str, int st, int end)` Write 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`

- - ### Field Detail

    - #### LCK

          private static final java.lang.String LCK

      The extension for the lock file.
      See Also:
        Constant Field Values

    - #### out

          private final java.io.Writer out

      The writer to decorate.

    - #### lockFile

          private final java.io.File lockFile

      The lock file.

  - ### Constructor Detail

    - #### LockableFileWriter

          public LockableFileWriter(java.lang.String fileName)
                             throws java.io.IOException

      Constructs a LockableFileWriter. If the file exists, it is overwritten.
      Parameters:
        `fileName` - the file to write to, not null
      Throws:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error

    - #### LockableFileWriter

          public LockableFileWriter(java.lang.String fileName,
                            boolean append)
                             throws java.io.IOException

      Constructs a LockableFileWriter.
      Parameters:
        `fileName` - file to write to, not null
        `append` - true if content should be appended, false to overwrite
      Throws:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error

    - #### LockableFileWriter

          public LockableFileWriter(java.lang.String fileName,
                            boolean append,
                            java.lang.String lockDir)
                             throws java.io.IOException

      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:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error

    - #### LockableFileWriter

          public LockableFileWriter(java.io.File file)
                             throws java.io.IOException

      Constructs a LockableFileWriter. If the file exists, it is overwritten.
      Parameters:
        `file` - the file to write to, not null
      Throws:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error

    - #### LockableFileWriter

          public LockableFileWriter(java.io.File file,
                            boolean append)
                             throws java.io.IOException

      Constructs a LockableFileWriter.
      Parameters:
        `file` - the file to write to, not null
        `append` - true if content should be appended, false to overwrite
      Throws:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error

    - #### LockableFileWriter

          @Deprecated
          public LockableFileWriter(java.io.File file,
                                       boolean append,
                                       java.lang.String lockDir)
                             throws java.io.IOException

      Deprecated. 2.5 use `LockableFileWriter(File, Charset, boolean, String)` instead
      Constructs a LockableFileWriter.
      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:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error

    - #### LockableFileWriter

          public LockableFileWriter(java.io.File file,
                            java.nio.charset.Charset encoding)
                             throws java.io.IOException

      Constructs a LockableFileWriter with a file encoding.
      Parameters:
        `file` - the file to write to, not null
        `encoding` - the encoding to use, null means platform default
      Throws:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error
      Since:
        2.3

    - #### LockableFileWriter

          public LockableFileWriter(java.io.File file,
                            java.lang.String encoding)
                             throws java.io.IOException

      Constructs a LockableFileWriter with a file encoding.
      Parameters:
        `file` - the file to write to, not null
        `encoding` - the encoding to use, null means platform default
      Throws:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error
        `java.nio.charset.UnsupportedCharsetException` - thrown instead of `UnsupportedEncodingException` in version 2.2 if the encoding is not supported.

    - #### LockableFileWriter

          public LockableFileWriter(java.io.File file,
                            java.nio.charset.Charset encoding,
                            boolean append,
                            java.lang.String lockDir)
                             throws java.io.IOException

      Constructs a LockableFileWriter with a file encoding.
      Parameters:
        `file` - the file to write to, not null
        `encoding` - 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:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error
      Since:
        2.3

    - #### LockableFileWriter

          public LockableFileWriter(java.io.File file,
                            java.lang.String encoding,
                            boolean append,
                            java.lang.String lockDir)
                             throws java.io.IOException

      Constructs a LockableFileWriter with a file encoding.
      Parameters:
        `file` - the file to write to, not null
        `encoding` - 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:
        `java.lang.NullPointerException` - if the file is null
        `java.io.IOException` - in case of an I/O error
        `java.nio.charset.UnsupportedCharsetException` - thrown instead of `UnsupportedEncodingException` in version 2.2 if the encoding is not supported.

  - ### Method Detail

    - #### testLockDir

          private void testLockDir(java.io.File lockDir)
                            throws java.io.IOException

      Tests that we can write to the lock directory.
      Parameters:
        `lockDir` - the File representing the lock directory
      Throws:
        `java.io.IOException` - if we cannot write to the lock directory
        `java.io.IOException` - if we cannot find the lock file

    - #### createLock

          private void createLock()
                           throws java.io.IOException

      Creates the lock file.
      Throws:
        `java.io.IOException` - if we cannot create the file

    - #### initWriter

          private java.io.Writer initWriter(java.io.File file,
                                  java.nio.charset.Charset encoding,
                                  boolean append)
                                     throws java.io.IOException

      Initialise the wrapped file writer. Ensure that a cleanup occurs if the writer creation fails.
      Parameters:
        `file` - the file to be accessed
        `encoding` - the encoding to use
        `append` - true to append
      Returns:
        The initialised writer
      Throws:
        `java.io.IOException` - if an error occurs

    - #### close

          public void close()
                     throws java.io.IOException

      Closes the file writer and deletes the lockfile (if possible).
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Specified by:
        `close` in class `java.io.Writer`
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### write

          public void write(int idx)
                     throws java.io.IOException

      Write a character.
      Overrides:
        `write` in class `java.io.Writer`
      Parameters:
        `idx` - the character to write
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### write

          public void write(char[] chr)
                     throws java.io.IOException

      Write the characters from an array.
      Overrides:
        `write` in class `java.io.Writer`
      Parameters:
        `chr` - the characters to write
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### write

          public void write(char[] chr,
                   int st,
                   int end)
                     throws java.io.IOException

      Write the specified characters from an array.
      Specified by:
        `write` in class `java.io.Writer`
      Parameters:
        `chr` - the characters to write
        `st` - The start offset
        `end` - The number of characters to write
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### write

          public void write(java.lang.String str)
                     throws java.io.IOException

      Write the characters from a string.
      Overrides:
        `write` in class `java.io.Writer`
      Parameters:
        `str` - the string to write
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### write

          public void write(java.lang.String str,
                   int st,
                   int end)
                     throws java.io.IOException

      Write the specified characters from a string.
      Overrides:
        `write` in class `java.io.Writer`
      Parameters:
        `str` - the string to write
        `st` - The start offset
        `end` - The number of characters to write
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### flush

          public void flush()
                     throws java.io.IOException

      Flush the stream.
      Specified by:
        `flush` in interface `java.io.Flushable`
      Specified by:
        `flush` in class `java.io.Writer`
      Throws:
        `java.io.IOException` - if an I/O error occurs

Copyright (c) 2002-2016 Apache Software Foundation