lumis.portal.filesystem

Class IFile

java.lang.Object

lumis.portal.filesystem.IFile

All Implemented Interfaces:

Serializable, IInputStreamProvider

Direct Known Subclasses:

ClusterMirroredLocalDataFile, LocalDataFile

@StableMinor(version="12.3",
             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: 23746 $ $Date: 2020-04-07 23:14:34 +0000 (Tue, 07 Apr 2020) $

See Also:

lumis.portal.filesystem, lumis.portal.filesystem.event, IFileSystem, IFileSystemManager.getFile(PortalFilePath), Serialized Form

Constructor Summary

Constructors

Constructor and Description
IFile(PortalFilePath portalFilePath) Creates a new instance with the given PortalFilePath.

Method Summary

Modifier and Type	Method and Description
protected void	copyRegularFileTo(IFile dest) Copies this file, assuming it is a regular file, to the specified destination.
void	copyTo(IFile dest) Copies the file denoted by this logical filesystem object.
abstract void	delete() Deletes the file or directory.
abstract void	deleteRecursively() Tries to delete the file or directory recursively.
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.
abstract boolean	exists() Tests whether the file or directory exists.
String	getExtension() Returns this file's extension or null if this file doesn't have an extension.
abstract InputStream	getInputStream() Returns an InputStream to be used to read this file.
abstract long	getLastModified() Returns the time that the file or directory was last modified.
abstract long	getLength() Returns the length of the file.
String	getName() Returns the name of the file or directory.
abstract OutputStream	getOutputStream() Returns an OutputStream that writes to this file.
IFile	getParent() Returns the parent directory.
PortalFilePath	getPath() Returns the PortalFilePath that represents this file or directory.
IFile	getRoot() Returns the root folder of this file.
int	hashCode() Makes use of PortalFilePath to calculate this hashcode.
boolean	isDescendentOf(IFile file) Returns whether this file is descendent of the given file.
abstract boolean	isDirectory() Tests whether the file is a directory.
boolean	isEmpty() Returns whether this directory is empty.
abstract boolean	isFile() Tests whether the file denoted by this IFile is an actual file.
boolean	isRoot() Returns whether this file is the root of its base folder.
abstract IFile[]	listFiles() Lists all immediate sub files and directories of this directory (the files and directories whose getParent() is equal to this).
IFile[]	listFiles(IFileFilter fileFilter) Lists all immediate sub files and directories of this directory (the files and directories whose getParent() is equal to this), respecting a given file filter.
abstract void	mkdirs() Creates the directory named by this logical filesystem object, including any necessary but nonexistent parent directories.
byte[]	readBytes() Reads this file content in bytes.
String	readString() Reads this file using the UTF-8 encoding.
String	readString(String charset) Reads this file using the given charset name.
String	relativize(IFile other) Relativizes the given file against this file.
void	renameTo(IFile dest) Renames the file denoted by this logical filesystem object.
IFile	resolve(String relativePath) Resolves the given path against this file.
abstract void	setLastModified(long time) Sets the last-modified time of the file or directory.
String	toString()
abstract URL	toURL() Returns a URL that represents this file.
void	write(byte[] buf) Writes the given bytes in this file.
void	write(File file) Writes the contents of the given file into this file.
void	write(InputStream inputStream) Copies the given input stream's content into this file.
void	write(String str) Writes the given string in this file using UTF-8 encoding.
void	write(String str, String charset) Writes the given string in this file using the given charset name.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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()

getParent

public IFile getParent()

Returns the parent directory. If this is already the root of the base folder defined in portal file path, null is returned. In other words, if getPath().getRelativePath() is an empty string, null is returned.

Returns:

the parent directory

Since:

8.0.0

See Also:

PortalFilePath.getParent()

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

isEmpty

public final boolean isEmpty()
                      throws FileNotFoundException,
                             FileIsNotDirectoryException,
                             IOException

Returns whether this directory is empty.

Returns:

whether this directory is empty.

Throws:

FileNotFoundException - if this file does not exist.

FileIsNotDirectoryException - if this file does not denote a directory.

IOException - if other error occur.

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

toString

public String toString()

Overrides:

toString in class Object

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

getLength

public abstract long getLength()
                        throws FileNotFoundException,
                               NotFileException,
                               IOException

Returns the length of the file.

Returns:

The length, in bytes, of the file.

Throws:

NotFileException - if this is not a file

FileNotFoundException - If this file does not exist

IOException - if other error occur

Since:

8.0.0

delete

public abstract void delete()
                     throws FileCouldNotBeDeletedException,
                            IOException

Deletes the file or directory. If this denotes a directory, then the directory must be empty in order to be deleted. If this file doesn't exist already, no exception will be raised.

Throws:

FileCouldNotBeDeletedException - if this file could not be deleted

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

listFiles

public abstract IFile[] listFiles()
                           throws FileNotFoundException,
                                  FileIsNotDirectoryException,
                                  IOException

Lists all immediate sub files and directories of this directory (the files and directories whose getParent() is equal to this).

Returns:

all immediate sub files and directories of this directory; an empty list if this directory has no files and no directories.

Throws:

FileNotFoundException - if this file doesn't exist

FileIsNotDirectoryException - if this file does not denote a directory

IOException - if other error occur

Since:

8.0.0

listFiles

public IFile[] listFiles(IFileFilter fileFilter)
                  throws FileNotFoundException,
                         FileIsNotDirectoryException,
                         IOException

Lists all immediate sub files and directories of this directory (the files and directories whose getParent() is equal to this), respecting a given file filter.

Parameters:

fileFilter - the file filter to be applied when searching sub files

Returns:

all immediate sub files and directories that matches the specified file filter of this directory; an empty list if this directory has no files and no directories.

Throws:

FileNotFoundException - if this file doesn't exist

FileIsNotDirectoryException - if this file does not denote a directory

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

renameTo

public void renameTo(IFile dest)
              throws FileCouldNotBeRenamedException,
                     FileNotFoundException,
                     IOException

Renames the file denoted by this logical filesystem object. This operation is equivalent to:

copyTo(dest);
deleteRecursively();

The rules of this operation follows the rules of copyTo(IFile) and deleteRecursively().

Parameters:

dest - The new logical filesystem object for the named file

Throws:

IllegalArgumentException - if dest is null

FileNotFoundException - if this file doesn't exist

FileCouldNotBeRenamedException - if the file could not be renamed for some reason

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

toURL

public abstract URL toURL()
                   throws IOException

Returns a URL that represents this file. The URL must, at least, provide means of accessing this file's input stream by implementing URLConnection.getInputStream().

Returns:

a URL that represents this file.

Throws:

IOException - if some error occur.

Since:

8.0.0