Class PosixFile


  • public class PosixFile
    extends Object
    Access and modify all the POSIX-specific file attributes. These updates are made using a Linux shared library provided as a resource. The source code is also supplied.

    Note: The JVM must be in a single-byte locale, such as "C", "POSIX", or "en_US". PosixFile makes this assumption in its JNI implementation.

    Author:
    AO Industries, Inc.
    • Constructor Detail

      • PosixFile

        @Deprecated
        public PosixFile​(PosixFile parent,
                         String path)
                  throws IOException
        Deprecated.
        Please call #PosixFile(PosixFile,String,boolean) to explicitly control whether strict parent checking is performed
        Creates a new POSIX file.

        Strictly requires the parent to be a directory if it exists.

        Throws:
        IOException
      • PosixFile

        public PosixFile​(PosixFile parent,
                         String path,
                         boolean strict)
                  throws IOException
        Creates a new POSIX file.
        Parameters:
        strict - When strictly checking, a parent must be a directory if it exists.
        Throws:
        IOException
      • PosixFile

        public PosixFile​(File file)
        Creates a new POSIX file.
      • PosixFile

        public PosixFile​(File parent,
                         String filename)
        Creates a new POSIX file.
      • PosixFile

        public PosixFile​(String path)
        Creates a new POSIX file.
      • PosixFile

        public PosixFile​(String parent,
                         String filename)
        Creates a new POSIX file.
    • Method Detail

      • loadLibrary

        public static void loadLibrary()
        Loads the shared library native code libaocode.so.
      • checkRead

        public final void checkRead()
                             throws IOException
        Ensures that the calling thread is allowed to read this PosixFile in any way.
        Throws:
        IOException
      • checkRead

        public static void checkRead​(String path)
                              throws IOException
        Ensures that the calling thread is allowed to read this path in any way.
        Throws:
        IOException
      • checkWrite

        public final void checkWrite()
                              throws IOException
        Ensures that the calling thread is allowed to write to or modify this PosixFile in any way.
        Throws:
        IOException
      • checkWrite

        public static void checkWrite​(String path)
                               throws IOException
        Ensures that the calling thread is allowed to write to or modify this path in any way.
        Throws:
        IOException
      • chown

        public final PosixFile chown​(int uid,
                                     int gid)
                              throws IOException
        Changes both the owner and group for a file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getStat

        public Stat getStat()
                     throws IOException
        Stats the file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • contentEquals

        public boolean contentEquals​(PosixFile otherFile)
                              throws IOException
        Compares this contents of this file to the contents of another file.

        This method will follow both path symbolic links and a final symbolic link.

        Throws:
        IOException
      • contentEquals

        public boolean contentEquals​(byte[] otherFile)
                              throws IOException
        Compares the contents of a file to a byte[].

        This method will follow both path symbolic links and a final symbolic link.

        Throws:
        IOException
      • secureContentEquals

        public boolean secureContentEquals​(PosixFile otherFile,
                                           int uidMin,
                                           int gidMin)
                                    throws IOException
        Compares this contents of this file to the contents of another file.

        This method will not follow any symbolic links and is not subject to race conditions.

        TODO: Java 1.8: Can do this in a pure Java way

        Throws:
        IOException
      • secureContentEquals

        public boolean secureContentEquals​(byte[] otherFile,
                                           int uidMin,
                                           int gidMin)
                                    throws IOException
        Compares the contents of a file to a byte[].

        This method will not follow any symbolic links and is not subject to race conditions.

        TODO: Java 1.8: Can do this in a pure Java way

        Throws:
        IOException
      • copyTo

        public void copyTo​(PosixFile otherFile,
                           boolean overwrite)
                    throws IOException
        Copies one filesystem object to another. It supports block devices, directories, fifos, regular files, and symbolic links. Directories are not copied recursively.

        This method will follow both path symbolic links and a final symbolic link.

        Throws:
        IOException
      • crypt

        public static String crypt​(String password,
                                   String salt)
        Hashes a password using the provided salt. The salt includes any salt prefix for the algorithm.

        Please refer to man 3 crypt for more details.

      • delete

        public final void delete()
                          throws IOException
        Deletes this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
        See Also:
        File.delete()
      • secureDeleteRecursive

        public final void secureDeleteRecursive​(int uidMin,
                                                int gidMin)
                                         throws IOException
        Securely deletes this file entry and all files below it while not following symbolic links. This method must be called with root privileges to properly avoid race conditions. If not running with root privileges, use deleteRecursive instead.

        In order to avoid race conditions, all directories above this directory will have their permissions set so that regular users cannot modify the directories. After each parent directory has its permissions set it will then check for symbolic links. Once all of the parent directories have been completed, the filesystem will recursively have its permissions reset, scans for symlinks, and deletes performed in such a way all race conditions are avoided. Finally, the parent directory permissions that were modified will be restored.

        TODO: Java 1.8: Can do this in a pure Java way

        Throws:
        IOException
        See Also:
        secureDeleteRecursive(com.aoapps.io.posix.PosixFile)
      • exists

        @Deprecated
        public final boolean exists()
                             throws IOException
        Deprecated.
        Please use getStat(Stat).exists()
        Determines if a file exists, a symbolic link with an invalid destination is still considered to exist.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getAccessTime

        @Deprecated
        public final long getAccessTime()
                                 throws IOException
        Deprecated.
        Please use getStat(Stat).getAccessTime()
        Gets the last access to this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getBlockCount

        @Deprecated
        public final long getBlockCount()
                                 throws IOException
        Deprecated.
        Please use getStat(State).getBlockCount()
        Gets the block count for this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getBlockSize

        @Deprecated
        public final int getBlockSize()
                               throws IOException
        Deprecated.
        Please use getStat(Stat).getBlockSize()
        Gets the block size for this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getChangeTime

        @Deprecated
        public final long getChangeTime()
                                 throws IOException
        Deprecated.
        Please use getStat(Stat).getChangeTime()
        Gets the change time of this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getDevice

        @Deprecated
        public final long getDevice()
                             throws IOException
        Deprecated.
        Please use getStat(Stat).getDevice()
        Gets the device for this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getDeviceIdentifier

        @Deprecated
        public final long getDeviceIdentifier()
                                       throws IOException
        Deprecated.
        Please use getStat(Stat).getDeviceIdentifier()
        Gets the device identifier for this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getExtension

        public final String getExtension()
        Gets the extension for this file.
      • getFile

        public final File getFile()
        Gets the File for this PosixFile. Not synchronized because multiple instantiation is acceptable.
      • getFilename

        @Deprecated
        public final String getFilename()
        Deprecated.
        the use of the word filename is misleading since it represents the entire path, please use getPath() instead.
        Gets the path for this PosixFile.
        See Also:
        getPath()
      • getPath

        public final String getPath()
        Gets the path for this PosixFile.
      • getGid

        @Deprecated
        public final int getGid()
                         throws IOException
        Deprecated.
        Please use getStat(Stat).getGid()
        Gets the group ID for this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getInode

        @Deprecated
        public final long getInode()
                            throws IOException
        Deprecated.
        Please use getStat(Stat).getInode()
        Gets the inode for this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getLinkCount

        @Deprecated
        public final int getLinkCount()
                               throws IOException
        Deprecated.
        Please use getStat(Stat).getNumberLinks()
        Gets the link count for this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getMode

        @Deprecated
        public final long getMode()
                           throws IOException
        Deprecated.
        Please use getStat(Stat).getMode()
        Gets the permission bits of the mode of this file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getModeString

        public static String getModeString​(long mode)
        Gets a String representation of a mode similar to the output of the POSIX ls command.
      • getModeString

        @Deprecated
        public final String getModeString()
                                   throws IOException
        Deprecated.
        Please use getStat(Stat).getModeString()
        Gets a String representation of the mode of this file similar to the output of the POSIX ls command.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getSecureInputStream

        public final FileInputStream getSecureInputStream​(int uidMin,
                                                          int gidMin)
                                                   throws IOException
        Securely gets a FileInputStream to this file, temporarily performing permission changes and ensuring that no symbolic links are anywhere in the path.

        TODO: Java 1.8: Can do this in a pure Java way

        Throws:
        IOException
      • getSecureOutputStream

        public final FileOutputStream getSecureOutputStream​(int uid,
                                                            int gid,
                                                            long mode,
                                                            boolean overwrite,
                                                            int uidMin,
                                                            int gidMin)
                                                     throws IOException
        Securely gets a FileOutputStream to this file, temporarily performing permission changes and ensuring that no symbolic links are anywhere in the path.

        TODO: Consider the impact of using mktemp instead of secureParents/restoreParents because there is the possibility that permissions may not be restored if the JVM is shutdown at that moment.

        TODO: Java 1.8: Can do this in a pure Java way

        Throws:
        IOException
      • getSecureRandomAccessFile

        public final RandomAccessFile getSecureRandomAccessFile​(String mode,
                                                                int uidMin,
                                                                int gidMin)
                                                         throws IOException
        Securely gets a RandomAccessFile to this file, temporarily performing permission changes and ensuring that no symbolic links are anywhere in the path.

        TODO: Java 1.8: Can do this in a pure Java way

        Throws:
        IOException
      • getParent

        public final PosixFile getParent()
        Gets the parent of this file or null if it doesn't have a parent. Not synchronized because multiple instantiation is acceptable.
      • getStatMode

        @Deprecated
        public final long getStatMode()
                               throws IOException
        Deprecated.
        Please use getStat(Stat).getRawMode()
        Gets the complete mode of the file, including the bits representing the file type.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getModifyTime

        @Deprecated
        public final long getModifyTime()
                                 throws IOException
        Deprecated.
        Please use getStat(Stat).getModifyTime()
        Gets the modification time of the file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getSize

        @Deprecated
        public final long getSize()
                           throws IOException
        Deprecated.
        Please use getStat(Stat).getSize()
        Gets the size of the file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • getUid

        @Deprecated
        public final int getUid()
                         throws IOException
        Deprecated.
        Please use getStat(Stat).getUid()
        Gets the user ID of the file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • isBlockDevice

        public static boolean isBlockDevice​(long mode)
        Determines if a specific mode represents a block device.
      • isBlockDevice

        @Deprecated
        public final boolean isBlockDevice()
                                    throws IOException
        Deprecated.
        Please use getStat(Stat).isBlockDevice()
        Determines if this file represents a block device.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • isCharacterDevice

        public static boolean isCharacterDevice​(long mode)
        Determines if a specific mode represents a character device.
      • isCharacterDevice

        @Deprecated
        public final boolean isCharacterDevice()
                                        throws IOException
        Deprecated.
        Please use getStat(Stat).isCharacterDevice()
        Determines if this file represents a character device.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • isDirectory

        public static boolean isDirectory​(long mode)
        Determines if a specific mode represents a directory.
      • isDirectory

        @Deprecated
        public final boolean isDirectory()
                                  throws IOException
        Deprecated.
        Please use getStat(Stat).isDirectory()
        Determines if this file represents a directory.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • isFifo

        public static boolean isFifo​(long mode)
        Determines if a specific mode represents a FIFO.
      • isFifo

        @Deprecated
        public final boolean isFifo()
                             throws IOException
        Deprecated.
        Please use getStat(Stat).isFifo()
        Determines if this file represents a FIFO.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • isRegularFile

        public static boolean isRegularFile​(long mode)
        Determines if a specific mode represents a regular file.
      • isRegularFile

        @Deprecated
        public final boolean isRegularFile()
                                    throws IOException
        Deprecated.
        Please use getStat(Stat).isRegularFile()
        Determines if this file represents a regular file.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • isRootDirectory

        public final boolean isRootDirectory()
        Determines if this file is the root directory.
      • isSocket

        public static boolean isSocket​(long mode)
        Determines if a specific mode represents a socket.
      • isSocket

        @Deprecated
        public final boolean isSocket()
                               throws IOException
        Deprecated.
        Please use getStat(Stat).isSocket()
        Determines if this file represents a socket.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • isSymLink

        public static boolean isSymLink​(long mode)
        Determines if a specific mode represents a symbolic link.
      • isSymLink

        @Deprecated
        public final boolean isSymLink()
                                throws IOException
        Deprecated.
        Please use getStat(Stat).isSymLink()
        Determines if this file represents a sybolic link.

        This method will follow symbolic links in the path but not a final symbolic link.

        Throws:
        IOException
      • list

        public final String[] list()
        Lists the contents of the directory.

        This method will follow symbolic links in the path, including a final symbolic link.

        See Also:
        File.list()
      • mkdir

        public final PosixFile mkdir​(boolean makeParents,
                                     long mode)
                              throws IOException
        Creates a directory and sets its permissions, optionally creating all the parent directories if they do not exist.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • mkdir

        public final PosixFile mkdir​(boolean makeParents,
                                     long mode,
                                     int uid,
                                     int gid)
                              throws IOException
        Creates a directory and sets its permissions, optionally creating all the parent directories if they do not exist.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • mknod

        public final PosixFile mknod​(long mode,
                                     long device)
                              throws IOException
        Creates a device file.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • mkfifo

        public final PosixFile mkfifo​(long mode)
                               throws IOException
        Creates a FIFO.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • setAccessTime

        @Deprecated
        public final PosixFile setAccessTime​(long atime)
                                      throws IOException
        Deprecated.
        This method internally performs an extra stat. Please try to use utime(long,long) directly to avoid this extra stat.
        Sets the access time for this file.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • setGid

        @Deprecated
        public final PosixFile setGid​(int gid)
                               throws IOException
        Deprecated.
        This method internally performs an extra stat. Please try to use chown(int,int) directly to avoid this extra stat.
        Sets the group ID for this file.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • setMode

        public final PosixFile setMode​(long mode)
                                throws IOException
        Sets the permissions for this file.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • setModifyTime

        @Deprecated
        public final PosixFile setModifyTime​(long mtime)
                                      throws IOException
        Deprecated.
        This method internally performs an extra stat. Please try to use utime(long,long) directly to avoid this extra stat.
        Sets the modification time for this file.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • setUid

        @Deprecated
        public final PosixFile setUid​(int uid)
                               throws IOException
        Deprecated.
        This method internally performs an extra stat. Please try to use chown(int,int) directly to avoid this extra stat.
        Sets the user ID for this file.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • readLink

        public final String readLink()
                              throws IOException
        Reads a symbolic link.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • utime

        public final PosixFile utime​(long atime,
                                     long mtime)
                              throws IOException
        Sets the access and modify times for this file.

        This method will follow symbolic links in the path.

        Throws:
        IOException
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object