Package ch.ivyteam.ivy.scripting.objects

Class File

java.lang.Object
ch.ivyteam.ivy.scripting.objects.File
All Implemented Interfaces:
IIvyDataObject, Serializable, Cloneable
public class File extends Object implements IIvyDataObject
A class for files; files are characterized by a path. Pathes are always normalized. The path can be relative or absolute; relative pathes are relative with respect to a base directory specified from IvyScriptObjectEnvironment. If a relative path goes specifies a field that is not a decendant of the base directory, it is replaced by the empty path (specifing the base directory).
See Also:
API:
This is a public API.

  • Constructor Summary

    Constructors
    Constructor
    Description
    File()
    Creates a new File which points to the application's persistent file area (i.e.
    File(String path)
    Creates a new persistent File with the given relative path.
    File(String path, boolean temporary)
    Creates a new File with the given relative path.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    canRead()
    Tests whether this file is readable.
    boolean
    canWrite()
    Tests whether this file can be modified.
    File
    clone()
    Creates a clone.
    void
    copy(File newFile, boolean override, boolean preserveFileDate)
    Copies this file to a new location.
    void
    copy(String newPath, boolean override, boolean preserveFileDate)
    Copies this file to a new location.
    boolean
    createNewFile()
    Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.
    File
    deepClone()
    Creates a clone; the same as clone().
    boolean
    delete()
    Deletes this file or directory.
    boolean
    equals(Object another)
    Test equaliy of files: two files are equals is the habe the same normalized absolute path.
    boolean
    exists()
    Tests whether the file or directory denoted by this file object exists.
    boolean
    forceDelete()
    Forcedly deletes this file or directory (even if it's not empty).
    String
    getAbsolutePath()
    Returns the absolute (and normalized) path of this file object.
    File
    getJavaFile()
     
    String
    getName()
    Returns the name of the file or directory denoted by this file object.
    String
    getParent()
    Returns the path of the parent file of this file.
    File
    getParentFile()
    Returns the parent file of this file.
    String
    getPath()
    Returns the relative path of this file object.
    int
    hashCode()
    A Hash for the file.
    boolean
    isDirectory()
    returns true if the file denoted by this object is a directory.
    boolean
    isFile()
    Tests whether the file denoted by this object is a normal file.
    boolean
    isTemporary()
    Returns true, if this is a temporary file.
    DateTime
    lastModified()
    Returns the time that the file was last modified.
    long
    lastModifiedMillis()
    Returns the time that the file was last modified.
    List<String>
    list()
    Returns a list of strings naming the files and directories in the directory denoted by this ivy file.
    List<File>
    listFiles()
    Returns a list of ivy files denoting the files in the directory denoted by this ivy file.
    File
    makePersistent(boolean overwrite)
    Makes a temporary file persistent.
    boolean
    mkdir()
    Creates the directory named by this aivy file, including any necessary but nonexistent parent directories.
    File
    move(File newFile, boolean override)
    Moves this file to the file in the argument.
    File
    move(String newPath, boolean override)
    Moves this file to the file specified by the path in the argument.
    String
    read()
    Reads the file content and returns it as a String; the default encoding is used.
    String
    read(String encoding)
    Reads the file content and returns it as a String.
    Binary
    readBinary()
    Reads the file content and returns it as a Binary.
    File
    rename(String newName, boolean override)
    Renames a file in the same directory.
    String
    toString()
    Returns the path of the file.
    void
    write(String content)
    Writes a given String in a file with the default encoding.
    void
    write(String content, String encoding)
    Writes a given String in a file with a given encoding.
    void
    writeBinary(Binary content)
    Writes a given Binary in a file.

  • Constructor Details

    • File

      public File() throws IOException
      Creates a new File which points to the application's persistent file area (i.e. the created file will be a directory). This has the same effect as creating a file with new File("",false).
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • File

      public File(String path) throws IOException
      Creates a new persistent File with the given relative path. The location of the file is relative to the application's persistent file area. This has the same effect as creating a file with new File(path,false).
      Parameters:
      path - a relative path
      Throws:
      IOException - if path is not valid (e.g. absolute)
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • File

      public File(String path, boolean temporary) throws IOException
      Creates a new File with the given relative path. The file will be either persistent or temporary, depending on the value of the temporary argument. The location of the file will be relative to the application's persistent or temporary file area, respectively.
      Parameters:
      path - a relative path
      temporary - if true then a temporary file will be created, otherwise a persistent file will be created
      Throws:
      IOException - if path is not valid (e.g. absolute)
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

  • Method Details

    • getJavaFile

      public File getJavaFile()
      Returns:
      The java.io.File object wrapped by this ivy-file.
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • getName

      public String getName()
      Returns the name of the file or directory denoted by this file object. This is just the last name in the pathname's name sequence. If the pathname's name sequence is empty, then the empty string is returned.
      Returns:
      The name of the file or directory.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getParent

      public String getParent()
      Returns the path of the parent file of this file. If this file is the base directory (i.e. no parents exist), then the parent path will be equal to the path of this file.
      Returns:
      The path of the parent of this file (or the path of this file, if no parent exists).
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getParentFile

      public File getParentFile() throws IOException
      Returns the parent file of this file. If this file is the base directory (i.e. no parents exist), then the parent file will be equal to this file.
      Returns:
      The parent of this file (or this file, if no parent exists).
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getPath

      public String getPath()
      Returns the relative path of this file object. The returned path is always relative to the active file area (i.e. session file area, if file is temporary or application file area if file is persistent).
      Returns:
      relative file path
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getAbsolutePath

      public String getAbsolutePath()
      Returns the absolute (and normalized) path of this file object.
      Returns:
      An absolute path.
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.

    • exists

      public boolean exists()
      Tests whether the file or directory denoted by this file object exists.
      Returns:
      true if file exists, false otherwise.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • isFile

      public boolean isFile()
      Tests whether the file denoted by this object is a normal file. A file is normal if it is not a directory and, in addition, satisfies other system-dependent criteria. Any non-directory file created by Ivyscript is guaranteed to be a normal file.
      Returns:
      true for files, false for directories.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • isDirectory

      public boolean isDirectory()
      returns true if the file denoted by this object is a directory.
      Returns:
      true if this is a directory.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • list

      public List<String> list()
      Returns a list of strings naming the files and directories in the directory denoted by this ivy file.

      If this ivy file does not denote a directory, then this method returns null. Otherwise a list of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path.

      There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.

      Returns:
      An array of strings naming the files and directories in the directory denoted by this ivy file. The array will be empty if the directory is empty. Returns null if this ivy file does not denote a directory, or if an I/O error occurs.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • listFiles

      public List<File> listFiles() throws IOException
      Returns a list of ivy files denoting the files in the directory denoted by this ivy file.

      If this ivy file does not denote a directory, then this method returns null. Otherwise a list of File objects is returned, one for each file or directory in the directory. Pathnames denoting the directory itself and the directory's parent directory are not included in the result. If this pathname is absolute then each resulting pathname is absolute; if this pathname is relative then each resulting pathname will be relative.

      There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.

      Returns:
      A list of abstract pathnames denoting the files and directories in the directory denoted by this abstract pathname. The list will be empty if the directory is empty. Returns null if this ivy file does not denote a directory, or if an I/O error occurs.
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • canRead

      public boolean canRead()
      Tests whether this file is readable.
      Returns:
      true if and only if this file exists and can be read; false otherwise
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • canWrite

      public boolean canWrite()
      Tests whether this file can be modified.
      Returns:
      true if and only if the file exists and can be modified; false otherwise.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • mkdir

      public boolean mkdir()
      Creates the directory named by this aivy file, 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.
      Returns:
      true if and only if the directory was created, along with all necessary parent directories; false otherwise
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • createNewFile

      public boolean createNewFile() throws IOException
      Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist. The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file.
      Returns:
      true if the named file does not exist and was successfully created; false if the named file already exists
      Throws:
      IOException - If an I/O error occurred
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • delete

      public boolean delete()
      Deletes this file or directory. If this is a directory, then the directory must be empty in order to be deleted.
      Returns:
      true if and only if the file or directory is successfully deleted; false otherwise
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • forceDelete

      public boolean forceDelete()
      Forcedly deletes this file or directory (even if it's not empty). If this is a directory, it is deleted recursively. For files, there is no difference between delete() and forceDelete().
      Returns:
      true if and only if the file or directory is successfully deleted; false otherwise
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • rename

      public File rename(String newName, boolean override) throws IOException
      Renames a file in the same directory.
      Parameters:
      newName - A simple file name.
      override -
      Returns:
      The new file if renaming is successful; just this file is returned if renaming is not possible.
      Throws:
      IOException - if the newFile exists and override is not allowed.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • move

      public File move(String newPath, boolean override) throws IOException
      Moves this file to the file specified by the path in the argument.

      The destination file will always be a persistent file independent of the status (temporary, persistent) of the source file.

      Many aspects of the behavior of this method are inherently platform-dependent: The rename operation might not be able to move a file from one filesystem to another, it might not be atomic.

      Parameters:
      newPath - The new destination
      override - Whether an already existing file may be overwritten.
      Returns:
      The new file if moving is successful; just this file is returned if moving is not possible.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to either the old or new pathnames
      NullPointerException - If parameter newPath is null
      IOException - if the newFile exists and override is not allowed.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • move

      public File move(File newFile, boolean override) throws IOException
      Moves this file to the file in the argument.

      Many aspects of the behavior of this method are inherently platform-dependent: The rename operation might not be able to move a file from one filesystem to another, it might not be atomic.

      Parameters:
      newFile - The new destination
      override - Whether an already existing file may be overwritten.
      Returns:
      The new file if moving is successful; just this file is returned if moving is not possible.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkWrite(java.lang.String) method denies write access to either the old or new pathnames
      NullPointerException - If parameter newPath is null
      IOException - if the newFile exists and override is not allowed.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • copy

      public void copy(String newPath, boolean override, boolean preserveFileDate) throws IOException
      Copies this file to a new location.

      The destination file will always be a persistent file independent of the status (temporary, persistent) of the source file.

      This method copies the contents of the specified source file to the specified destination file. The directory holding the destination file is created if it does not exist.

      Parameters:
      newPath - the path of the new file, must not be null.
      override - Whether it is allowed to oberride an existing file.
      preserveFileDate - true if the file date of the copy should be the same as the original
      Throws:
      NullPointerException - if source or destination is null
      IOException - if source or destination is invalid
      IOException - if an IO error occurs during copying
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • copy

      public void copy(File newFile, boolean override, boolean preserveFileDate) throws IOException
      Copies this file to a new location.

      This method copies the contents of the specified source file to the specified destination file. The directory holding the destination file is created if it does not exist.

      Parameters:
      newFile - the new location, must not be null.
      override - Whether it is allowed to oberride an existing file.
      preserveFileDate - true if the file date of the copy should be the same as the original
      Throws:
      NullPointerException - if source or destination is null
      IOException - if source or destination is invalid
      IOException - if an IO error occurs during copying
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • isTemporary

      public boolean isTemporary()
      Returns true, if this is a temporary file.
      Returns:
      true if temporary, false if persistent
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • makePersistent

      public File makePersistent(boolean overwrite) throws IOException
      Makes a temporary file persistent. This method has no effect, if the file is already persistent (i.e. if isTemporary() == false).

      If there's already a persistent file with the name of this temporary file then the existing file will either be overwritten or renamed, depending on the value of the overwrite parameter.

      If overwrite == false then this file will be renamed to an unused name, i.e. the resulting persistent file's name may be different after the makePersistent operation. The new name will be something like fileName{Number}.ext.

      When persisted, a file is moved from a temporary file space into a persistent file space. The old (temporary) file will no longer exist after a successful makePersistent operation.

      Parameters:
      overwrite - if true any existing persistent file with same name will be overwritten, if false then this file will be renamed after the operation
      Returns:
      The new file, persistent (with possibly different name).
      Throws:
      IOException - if operation fails.
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • read

      public String read() throws IOException
      Reads the file content and returns it as a String; the default encoding is used.
      Returns:
      The file content or null.
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • read

      public String read(String encoding) throws IOException
      Reads the file content and returns it as a String.
      Parameters:
      encoding - The file encoding.
      Returns:
      The file content or null.
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • readBinary

      public Binary readBinary() throws IOException
      Reads the file content and returns it as a Binary.
      Returns:
      The file content or null.
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • write

      public void write(String content) throws IOException
      Writes a given String in a file with the default encoding.
      Parameters:
      content - The file content
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • write

      public void write(String content, String encoding) throws IOException
      Writes a given String in a file with a given encoding.
      Parameters:
      content - The file content
      encoding -
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • writeBinary

      public void writeBinary(Binary content) throws IOException
      Writes a given Binary in a file.
      Parameters:
      content - The file content
      Throws:
      IOException
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • equals

      public boolean equals(Object another)
      Test equaliy of files: two files are equals is the habe the same normalized absolute path.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • hashCode

      public int hashCode()
      A Hash for the file.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • lastModifiedMillis

      public long lastModifiedMillis()
      Returns the time that the file 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), or 0L if the file does not exist or if an I/O error occurs
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • lastModified

      public DateTime lastModified()
      Returns the time that the file was last modified.
      Returns:
      A DateTime object indicating the last modification or null.
      Throws:
      SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • clone

      public File clone()
      Creates a clone.
      Specified by:
      clone in interface IIvyDataObject
      Returns:
      A clone.
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • deepClone

      public File deepClone()
      Creates a clone; the same as clone().
      Specified by:
      deepClone in interface IIvyDataObject
      Returns:
      A clone.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • toString

      public String toString()
      Returns the path of the file.
      Returns:
      the path of the file.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.