Package lumis.portal.filesystem

Class IFile

  • All Implemented Interfaces:
    Serializable, IInputStreamProvider
    Direct Known Subclasses:
    ClusterMirroredLocalDataFile, LocalDataFile
    @StableMinor(version="14.0",
             sinceVersion="8.0")
public abstract class IFile
extends Object
implements Serializable, IInputStreamProvider
    Represents a LumisPortal file or directory that may or may not exist.

    It uses a PortalFilePath to normalize the file or directory among the cluster servers and exposes the supported file and directory operations. Once created, its PortalFilePath is immutable. The PortalFilePath also is used to check whether this IFile is equal to another (see equals(Object)).

    In some implementations the changes made in one cluster server might take a while to be reflected in the other servers.

    Implementations must raise the appropriate filesystem events as file systems changes are performed using this API.

    Implementations must guarantee the read/write file integrity. The following must be guaranteed (even in highly concurrent scenarios):

    • The read operation must be able to read the entire file content without garbling with simultaneous writes
    • The write operation must be able to write the entire file content without garbling with simultaneous writes
    To accomplish this, some implementations may use locks.

    Any changes must take effect immediately, so that if the value is read immediately after the change operation, the returned value is the one that has been set, once the commands are called in the same cluster server.
    However, the same functionality is not guarantee if the change operation and the read operation are called in different cluster servers.
    But if a file operation is performed through a cluster transmission with a total order flag set, this file operation (in any server) must happen after any file operation performed before the transmission was sent in the cluster server that sent the transmission.

    Since:
    8.0.0
    Version:
    $Revision: 24477 $ $Date: 2021-04-28 11:30:36 -0300 (Wed, 28 Apr 2021) $
    See Also:
    lumis.portal.filesystem, lumis.portal.filesystem.event, IFileSystem, IFileSystemManager.getFile(PortalFilePath), Serialized Form

    • Constructor Detail

      • IFile

        public IFile​(PortalFilePath portalFilePath)
        Creates a new instance with the given PortalFilePath.
        Parameters:
        portalFilePath - the portal file path.
        Since:
        8.0.0

    • Method Detail

      • getName

        public final String getName()
        Returns the name of the file or directory. This is just the last name in the name sequence. If the relative path is empty (see PortalFilePath.getRelativePath()), then the empty string is returned.
        Returns:
        The name of the file or directory, or the empty string if this name sequence is empty
        Since:
        8.0.0
        See Also:
        PortalFilePath.getName()

      • resolve

        public IFile resolve​(String relativePath)
        Resolves the given path against this file. The path must not be an absolute path. In other words, it cannot begin with a /.

        The path of a file is composed by elements separated by /. The resolve process consists in create a new file using this file's relative path concatenated with a / and the given relative path. If the given relative path contains an element .. it means this .. and the previous element will be eliminated (for example my/folder/../file.txt will become my/file.txt).

        Parameters:
        relativePath - the relative path to be resolved.
        Returns:
        a file relative to this one.
        Throws:
        IllegalArgumentException - if path is null or it starts with a /.
        Since:
        8.0.0
        See Also:
        PortalFilePath.resolve(String)

      • isRoot

        public final boolean isRoot()
        Returns whether this file is the root of its base folder.
        Returns:
        whether this file is the root of its base folder.
        Since:
        8.0.0

      • isDescendentOf

        public final boolean isDescendentOf​(IFile file)
        Returns whether this file is descendent of the given file.
        Parameters:
        file - the file to be tested.
        Returns:
        whether this file is descendent of the given file.
        Since:
        8.0.0

      • relativize

        public final String relativize​(IFile other)
        Relativizes the given file against this file. Returns the relativized path or null if the given file couldn't be relativized. The given file can only be relativized against this one if it is descendent of this file.
        Parameters:
        other - the file to be relativized.
        Returns:
        the relative path or null if it couldn't be relativized.
        Since:
        8.0.0
        See Also:
        PortalFilePath.relativize(PortalFilePath)

      • getRoot

        public IFile getRoot()
        Returns the root folder of this file. If this file is already the root, then an equivalent object will be returned.
        Returns:
        the root folder of this file.
        Since:
        8.0.0

      • getPath

        public final PortalFilePath getPath()
        Returns the PortalFilePath that represents this file or directory. This method never returns null.
        Returns:
        the PortalFilePath that represents this file or directory
        Since:
        8.0.0

      • getExtension

        public final String getExtension()
                          throws IOException
        Returns this file's extension or null if this file doesn't have an extension. The extension is the remaining part of file name after the last . character.
        Returns:
        this file's extension.
        Throws:
        IOException - if some error occur.
        Since:
        8.0.0

      • hashCode

        public final int hashCode()
        Makes use of PortalFilePath to calculate this hashcode. Indeed, they are exactly the same.
        Overrides:
        hashCode in class Object
        Returns:
        the hashcode.
        Since:
        8.0.0

      • equals

        public final boolean equals​(Object obj)
        Makes use of PortalFilePath to check if this object represents the same file system logical object represented by the given object.

        Indeed, the following is always true for two (not null) given IFile — file1 and file2:

        file1.equals(file2) if and only if file1.getPath().equals(file2.getPath())
        and also:
        if file1.getPath().equals(file2.getPath()) is true then file1.equals(file2) is also true
        Overrides:
        equals in class Object
        Parameters:
        obj - the other object to be tested against
        Returns:
        true if this object is equal to the given object, false otherwise
        Since:
        8.0.0

      • exists

        public abstract boolean exists()
                        throws IOException
        Tests whether the file or directory exists.
        Returns:
        true if and only if the file or directory exists; false otherwise
        Throws:
        IOException - if some error occur during this operation
        Since:
        8.0.0

      • isDirectory

        public abstract boolean isDirectory()
                             throws IOException
        Tests whether the file is a directory.
        Returns:
        true if and only if the file exists and is a directory; false otherwise
        Throws:
        IOException - if some error occur during this operation
        Since:
        8.0.0

      • isFile

        public abstract boolean isFile()
                        throws IOException
        Tests whether the file denoted by this IFile is an actual file. This test might be system-dependent.
        Returns:
        true if and only if the file denoted by this IFile exists and is an actual file; false otherwise
        Throws:
        IOException - if some error occur during this operation
        Since:
        8.0.0

      • setLastModified

        public abstract void setLastModified​(long time)
                              throws FileNotFoundException,
                                     IOException
        Sets the last-modified time of the file or directory.
        Parameters:
        time - The new last-modified time, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
        Throws:
        IllegalArgumentException - If the argument is negative
        FileNotFoundException - If this file does not exist
        IOException - if other error occur
        Since:
        8.0.0

      • getLastModified

        public abstract long getLastModified()
                              throws FileNotFoundException,
                                     IOException
        Returns the time that the file or directory was last modified.
        Returns:
        A long value representing the time the file was last modified, measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
        Throws:
        FileNotFoundException - If this file does not exist
        IOException - if other error occur
        Since:
        8.0.0

      • deleteRecursively

        public abstract void deleteRecursively()
                                throws FileCouldNotBeDeletedException,
                                       IOException
        Tries to delete the file or directory recursively. If the deletion of some file or directory fails the deletion will not be complete, but some files and/or directories might already have been deleted.

        In other words, it is not guaranteed that either all files and directories will be deleted or none of the files and directories will be deleted.

        If this file doesn't exist already, no exception will be raised.

        Throws:
        FileCouldNotBeDeletedException - if some file or directory couldn't be deleted
        IOException - if other error occur
        Since:
        8.0.0

      • mkdirs

        public abstract void mkdirs()
                     throws DirectoryCouldNotBeCreatedException,
                            IOException
        Creates the directory named by this logical filesystem object, including any necessary but nonexistent parent directories. Note that if this operation fails it may have succeeded in creating some of the necessary parent directories.
        Throws:
        DirectoryCouldNotBeCreatedException - if some of the needed directories could not be created
        IOException - if other error occur
        Since:
        8.0.0

      • copyTo

        public void copyTo​(IFile dest)
            throws FileNotFoundException,
                   FileCouldNotBeCopiedException,
                   IOException
        Copies the file denoted by this logical filesystem object.

        This operation will copy this file or directory to the target file or directory using the following criteria:

        • If this file does not exist, a FileNotFoundException will be raised.
        • If this file is a regular file:
          • If the target file does not exist, the target file will be created using this file's content.
          • If the target file is an already existent regular file, the target's content will be replaced by this file's content.
          • If the target file is not a regular file, a FileNotFoundException will be raised.
        • If this file is a directory:
          • If the target file does not exist, the target file will be created as a directory and this file's children will be copied recursively.
          • If the target file is a directory, this file's children will be copied recursively. Those files that already existed in the target but does not exist in this file will not be removed.
          • If the target file exists and is not a directory, a FileNotFoundException will be raised.
          In the case this file is a directory, it is important to notice that if some error occur during the copy of some subfile, some files might already have been copied and/or some directories might already have been created.
        • If this file exists but it isn't neither a regular file nor a directory, a FileNotFoundException will be raised.
        Parameters:
        dest - The new logical filesystem object for the named file
        Throws:
        FileNotFoundException - if this file doesn't exist
        FileCouldNotBeCopiedException - if some error occur during copy
        IOException - if other error occur
        Since:
        8.0.0

      • copyRegularFileTo

        protected void copyRegularFileTo​(IFile dest)
                          throws IOException
        Copies this file, assuming it is a regular file, to the specified destination.
        Parameters:
        dest - the copy destination.
        Throws:
        IOException - if I/O error occurred.
        Since:
        12.0.0

      • getInputStream

        public abstract InputStream getInputStream()
                                    throws IOException
        Returns an InputStream to be used to read this file.

        If the named file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading then a FileNotFoundException is thrown.

        The stream must be closed by the caller of this method. A try-finally statement is recommended to guarantee it is closed.

        Specified by:
        getInputStream in interface IInputStreamProvider
        Returns:
        an InputStream to be used to read this file.
        Throws:
        FileNotFoundException - If the named file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading
        IOException - If an I/O error occurred
        Since:
        8.0.0

      • getOutputStream

        public abstract OutputStream getOutputStream()
                                      throws IOException
        Returns an OutputStream that writes to this file.

        Any existent content in the file will be discarded and replaced with the content written to this output stream.

        The new file content will only be available after OutputStream.close() is called.

        If the file exists but is a directory rather than a regular file, does not exist but cannot be created, the parent directory does not exist, or cannot be opened for any other reason then a FileNotFoundException is thrown. This exception can be thrown in at any time between this call and the call of OutputStream.close().

        The stream must be closed by the caller of this method. A try-finally statement is recommended to guarantee it is closed.

        Returns:
        an OutputStream to be used to write this file.
        Throws:
        FileNotFoundException - If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
        IOException - If an I/O error occurred
        Since:
        8.0.0

      • readString

        public final String readString()
                        throws IOException
        Reads this file using the UTF-8 encoding.
        Returns:
        the file content.
        Throws:
        IOException
        Since:
        8.0.0

      • readString

        public final String readString​(String charset)
                        throws IOException
        Reads this file using the given charset name.
        Parameters:
        charset - the charset name
        Returns:
        the file content.
        Throws:
        IOException
        Since:
        8.0.0

      • readBytes

        public byte[] readBytes()
                 throws IOException
        Reads this file content in bytes.
        Returns:
        this file content in bytes.
        Throws:
        IOException
        Since:
        8.0.0

      • write

        public final void write​(byte[] buf)
                 throws IOException
        Writes the given bytes in this file.
        Parameters:
        buf - the bytes to be written.
        Throws:
        IOException
        Since:
        8.0.0

      • write

        public final void write​(String str,
                        String charset)
                 throws IOException
        Writes the given string in this file using the given charset name.
        Parameters:
        str - the string to be written.
        charset - the charset name
        Throws:
        IOException
        Since:
        8.0.0

      • write

        public final void write​(String str)
                 throws IOException
        Writes the given string in this file using UTF-8 encoding.
        Parameters:
        str - the string to be written.
        Throws:
        IOException
        Since:
        8.0.0

      • write

        public void write​(InputStream inputStream)
           throws IOException
        Copies the given input stream's content into this file.
        Parameters:
        inputStream - the input stream.
        Throws:
        IOException
        Since:
        8.0.0

      • write

        public final void write​(File file)
                 throws IOException
        Writes the contents of the given file into this file.
        Parameters:
        file - the file with the desired contents.
        Throws:
        IOException - if some error occur.
        Since:
        8.0.0