Package org.dellroad.stuff.io

Class FileStreamRepository

java.lang.Object
org.dellroad.stuff.io.FileStreamRepository
All Implemented Interfaces:
Serializable, StreamRepository
public class FileStreamRepository extends Object implements StreamRepository, Serializable
Provides a file-based implementation of the StreamRepository interface with the added feature of automated backups.

Atomic updates are implemented using an AtomicUpdateFileOutputStream.

When backups are configured, the base file must be copied, not moved, to the first backup on update to avoid a small window where the base file doesn't exist. This class uses hard links to perform this "copy" efficiently. This behavior can be altered by overriding copy() on systems not supporting hard links.

See Also:

  • Constructor Details

    • FileStreamRepository

      public FileStreamRepository(File file, int numBackups)
      Primary constructor.
      Parameters:
      file - the file that will store the stream content
      numBackups - number of backup copies to keep
      Throws:
      IllegalArgumentException - if file is null
      IllegalArgumentException - if numBackups is negative

    • FileStreamRepository

      public FileStreamRepository(File file)
      Convenience constructor for the case where no backup copies are needed.

      Equivalent to:

      FileStreamRepository(file, 0);
      Parameters:
      file - the file that will store the stream content

  • Method Details

    • getFile

      public final File getFile()
      Get the configured File.
      Returns:
      the file that stores the stream content (same as given to constructor)

    • getNumBackups

      public final int getNumBackups()
      Get the configured number of backup files.
      Returns:
      the number of backup files to maintain

    • setNumBackups

      public void setNumBackups(int numBackups)
      Change the number of backup files to maintain.

      If the number of backups is reduced, the "extra" backup files are not touched.

      Parameters:
      numBackups - number of backup files
      Throws:
      IllegalArgumentException - if numBackups is less than zero

    • getInputStream

      public InputStream getInputStream() throws IOException
      Description copied from interface: StreamRepository
      Get an input stream reading the current value of the underlying store.
      Specified by:
      getInputStream in interface StreamRepository
      Returns:
      input containing current repository contents
      Throws:
      IOException - if an error occurs

    • getOutputStream

      public AtomicUpdateFileOutputStream getOutputStream() throws IOException
      Description copied from interface: StreamRepository
      Get an output stream writing to the underlying store. The underlying store is not modified until if/when the returned output stream is successfully closed, at which time it is atomically updated with the newly written content.

      If the returned stream throws an IOException at any time, including during close(), or if close() is never invoked, then no update to the underlying storage occurs.

      Specified by:
      getOutputStream in interface StreamRepository
      Returns:
      output for overwriting the current repository contents
      Throws:
      IOException - if an error occurs

    • getFileTimestamp

      public long getFileTimestamp()
      Get the last modification timestamp of the target file as known to this instance.

      This returns the modification timestamp as known by this instance; it does not ask the filesystem for the actual last modification timestamp. So if the two are different, then the file has been updated by some external process. In other words, this returns the modification timestamp of the underlying file as it was at the time of the most recent update.

      Returns:
      file's last modification timestamp as known by this instance, or zero if the file has not yet been successfully written to

    • getBackupFile

      protected File getBackupFile(File file, int index)
      Generate a backup file name.

      The implementation in FileStreamRepository returns a file with the same name as file plus a suffix .1, .2, .3, etc. corresponding to index. Subclasses may override as desired.

      Parameters:
      file - the file that stores the current stream content (i.e., from getFile())
      index - backup index, always greater than or equal to 1
      Returns:
      the index'th backup file for file

    • copy

      protected void copy(File src, File dst) throws IOException
      Copy, via hard link if possible, a file. If the two files are the same, nothing should be done.

      The implementation in FileStreamRepository uses hard links. Subclasses must override this method if the platform does not support hard links.

      Parameters:
      src - source file
      dst - destination file
      Throws:
      IOException - if unsuccessful