Package org.bzdev.io

Class FileAccessor

java.lang.Object
org.bzdev.io.FileAccessor

public class FileAccessor extends Object
Class to provide access to a file. Permission to access the file as specified by a mode argument must be granted when a constructor is called. An input stream, output stream, or a RandomAccessFile can then be obtained using the permission granted to this class. The modes are combinations of the following letters:
  • "r" - the file accessor can open an input stream or a random-access file with read access.
  • "w" - the file accessor can open an output stream or a random-access file with write access.
  • "a" - if the file accessor opens an output stream, the data written to that output stream will be appended to the file.
All combinations of these three letters are allowed. The permissions implied by "r" and "w" apply to capabilities of an instance of FileAccessor, not to file-system permissions.

The caller must have the necessary permissions to create or modify the specified file when the constructor is called. The methods getInputStream, getOutputStream, and getRandomAccessFile provide access to an input stream, output stream, and RandomAccessFile regardless of the permissions when these methods are called.

For example, a program using a command-line interface might parse the command line and create a FileAccessor for each file that an application was going to open, either for reading or writing. Later, the application could use the file accessors to open input or output streams as needed, ensuring that the maximum number of open files for the JVM is not exceeded: when a FileAccessor is created, the corresponding file is not opened immediately. The original use case for this class was one in which files had to be opened after a security manager was installed, but security managers exist only in earlier versions of Java.

  • Constructor Details

    • FileAccessor

      public FileAccessor(String filename) throws IOException, NullPointerException
      Constructor given a file name.
      Parameters:
      filename - the name of the file to access
      Throws:
      IOException - the file, most likely a portion of its path cannot be found or is not accessible
      NullPointerException - the argument was null
    • FileAccessor

      public FileAccessor(String filename, String mode) throws IOException, NullPointerException
      Constructor given a file name and mode. The modes are strings containing the following letters:
      • "r" - the file accessor can open an input stream.
      • "w" - the file accessor can open an output stream.
      • "a" - if the file accessor opens an output stream, the data written to that output stream will be appended to the file.
      Parameters:
      filename - the name of the file to access
      mode - the file-accessor mode (a combination of 'r', 'w', and 'a')
      Throws:
      IOException - the file, most likely a portion of its path, cannot be found or is not accessible
      NullPointerException - the first argument was null
    • FileAccessor

      public FileAccessor(File file) throws IOException, NullPointerException
      Constructor given a File.
      Parameters:
      file - the file to access
      Throws:
      IOException - the file, most likely a portion of its path cannot be found or is not accessible
      NullPointerException - the argument was null
    • FileAccessor

      public FileAccessor(File file, String mode) throws IOException, NullPointerException
      Constructor given a File and mode. The modes are strings containing the following letters:
      • "r" - the file accessor can open an input stream.
      • "w" - the file accessor can open an output stream.
      • "a" - if the file accessor opens an output stream, the data written to that output stream will be appended to the file. The file may not be opened as a random access file for writing
      Parameters:
      file - the file to access
      mode - the file-accessor mode (a combination of 'r', 'w', and 'a')
      Throws:
      IOException - the file, most likely a portion of its path cannot be found or is not accessible
      NullPointerException - the first argument was null
  • Method Details

    • getName

      public String getName()
      Get the name of the file corresponding to this file accessor.
      Returns:
      the last component of the file name
    • isReadable

      public boolean isReadable()
      Test if the file associated with this file accessor is readable and this file accessor allows reading.
      Returns:
      true if the file is readable; false if not
    • isWritable

      public boolean isWritable()
      Test if the file associated with this file accessor is writable and this file accessor allow writing.
      Returns:
      true if the file is writable; false if not
    • exists

      public boolean exists()
      Test if the file associated with this file accessor is writable and this file accessor allow writing.
      Returns:
      true if the file is writable; false if not
    • lastModified

      public long lastModified()
      Returns the time that the file referenced by this file accessor was last modified. The value returned may be negative, indicating the number of milliseconds before the epoch.
      Returns:
      the time the file was last modified in milliseconds since the epoch (00:00:00: GMT, January 1, 1970); 0L if an IO error occurs
      See Also:
    • length

      public long length()
      Returns the length of the file referenced by this file accessor.
      Returns:
      the length of the file in bytes
      See Also:
    • isAppendOnly

      public boolean isAppendOnly()
      Test if data must be appended to the file associated with this file accessor. A separate test is needed to determine if the file is writable.
      Returns:
      true if data must be appended; false otherwise
    • isDirectory

      public boolean isDirectory()
      Determine if the file referenced by this file accessor is a directory.
      Returns:
      true if it is a directory; false otherwise
    • getInputStream

      public InputStream getInputStream() throws IOException
      Get an input stream for reading from the file.
      Returns:
      an input stream for reading from the file specified by a constructor
      Throws:
      IOException - an IO error occurred or this file accessor does not allow a file to be read
    • getOutputStream

      public OutputStream getOutputStream() throws IOException
      Get an output stream for writing to the file.
      Returns:
      an output stream for writing to the file specified by a constructor
      Throws:
      IOException - an IO error occurred or this file accessor does not allow a file to be written
    • getRandomAccessFile

      public RandomAccessFile getRandomAccessFile() throws IOException
      Open the file for random access.
      Returns:
      an instance of RandomAccessFile, which provides random access to the file specified in a constructor
      Throws:
      IOException - an IO error occurred or this file accessor does not allow a file to be read or written
    • getDirectoryAccessor

      public DirectoryAccessor getDirectoryAccessor() throws IOException
      Get a directory accessor when this file accessor refers to a directory.
      Returns:
      a directory accessor; null if the file is not a directory or if this accessor is not readable.
      Throws:
      IOException - an IO error occurred
    • getDirectoryAccessor

      public DirectoryAccessor getDirectoryAccessor(boolean readOnly) throws IOException
      Get a directory accessor when this file accessor refers to a directory, specifying if the directory accessor is read only.
      Parameters:
      readOnly - true if this directory accessor is read only; false otherwise
      Returns:
      a directory accessor; null if the file is not a directory or if this accessor is not readable.
      Throws:
      IOException - an IO error occurred
    • delete

      public boolean delete() throws IOException, IllegalStateException
      Delete the file corresponding to this file accessor. The directory access must allow a file to be written, as must the corresponding file.
      Returns:
      true if the deletion was successful; false if not
      Throws:
      IOException - an IO error occurred
      IllegalStateException - this file accessor is not writable
    • move

      Move the file associated with this file accessor to the file specified by another file accessor.
      Parameters:
      fa - the file accessor for the target file
      options - copy options, each of which is either StandardCopyOption.ATOMIC_MOVE or StandardCopyOption.REPLACE_EXISTING
      Throws:
      UnsupportedOperationException - if an option is not recognized
      IOException - an IO error occurred
      FileAlreadyExistsException - if the target file exists but cannot be replaced because the REPLACE_EXISTING option was not specified
      DirectoryNotEmptyException - if the target file exists but cannot be replaced because it is a non-empty directory
      IllegalStateException
      See Also:
    • copy

      Copy the file associated with this file accessor to the file specified by another file accessor.
      Parameters:
      fa - the file accessor for the target file
      options - copy options, each of which is either LinkOption.NOFOLLOW_LINKS StandardCopyOption.COPY_ATTRIBUTES or StandardCopyOption.REPLACE_EXISTING
      Throws:
      UnsupportedOperationException - if an option is not recognized
      IOException - an IO error occurred
      FileAlreadyExistsException - if the target file exists but cannot be replaced because the REPLACE_EXISTING option was not specified
      DirectoryNotEmptyException - if the target file exists but cannot be replaced because it is a non-empty directory
      IllegalStateException
      See Also: