Package ch.ivyteam.ivy.scripting.objects

Class File

java.lang.Object
ch.ivyteam.ivy.scripting.objects.File
All Implemented Interfaces:
DataStreamProvider, IIvyDataObject, Serializable, Cloneable
public class File extends Object implements IIvyDataObject, DataStreamProvider
A class for files; files are characterized by a path. Paths are always normalized. The path can be relative or absolute; relative paths are relative with respect to a base directory specified from IvyScriptObjectEnvironment. If a relative path goes specifies a field that is not a descendant of the base directory, it is replaced by the empty path (specifying 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. the created file will be a directory).
    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()
    Clones the object (shallow 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 and returns a copy of this object.
    boolean
    delete()
    Deletes this file or directory.
    boolean
    equals(Object another)
     
    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()
    The File object wrapped by this File.
    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()
     
    boolean
    isDirectory()
    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 with the default encoding.
    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()
     
    void
    write(String content)
    Writes the given String in a file with the default encoding.
    void
    write(String content, String encoding)
    Writes the given String in a file with a given encoding.
    void
    writeBinary(Binary content)
    Writes the 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 - if the file can not be created
      API:
      This public API is available in Java.

    • 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 Java.

    • 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 Java.

  • Method Details

    • getJavaFile

      public File getJavaFile()
      The File object wrapped by this File.
      Returns:
      java file
      API:
      This public API is available in Java.

    • 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:
      name of the file or directory
      API:
      This public API is available in Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • getAbsolutePath

      public String getAbsolutePath()
      Returns the absolute (and normalized) path of this file object.
      Returns:
      absolute path
      API:
      This public API is available in Java.

    • exists

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

    • 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 if this is file otherwise false
      API:
      This public API is available in Java.

    • isDirectory

      public boolean isDirectory()
      True if the file denoted by this object is a directory.
      Returns:
      true if this is a directory otherwise false
      API:
      This public API is available in Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 Java.

    • 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 override 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 Java.

    • 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 override 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 Java.

    • 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 Java.

    • 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 Java.

    • read

      public String read() throws IOException
      Reads the file content and returns it as a String with the default encoding.
      Returns:
      file content or null
      Throws:
      IOException - if the file can not be read
      API:
      This public API is available in Java.

    • read

      public String read(String encoding) throws IOException
      Reads the file content and returns it as a String.
      Parameters:
      encoding - file encoding
      Returns:
      file content or null
      Throws:
      IOException - if the file can not be read
      API:
      This public API is available in Java.

    • readBinary

      public Binary readBinary() throws IOException
      Reads the file content and returns it as a Binary.
      Returns:
      file content or null
      Throws:
      IOException - if the file can not be read
      API:
      This public API is available in Java.

    • write

      public void write(String content) throws IOException
      Writes the given String in a file with the default encoding.
      Parameters:
      content - file content
      Throws:
      IOException - if the file can not be written
      API:
      This public API is available in Java.

    • write

      public void write(String content, String encoding) throws IOException
      Writes the given String in a file with a given encoding.
      Parameters:
      content - file content
      encoding - encoding
      Throws:
      IOException - if the file can not be written
      API:
      This public API is available in Java.

    • writeBinary

      public void writeBinary(Binary content) throws IOException
      Writes the given Binary in a file.
      Parameters:
      content - file content
      Throws:
      IOException - if the file can not be written
      API:
      This public API is available in Java.

    • equals

      public boolean equals(Object another)
      API:
      This public API is available in Java.

    • hashCode

      public int hashCode()
      API:
      This public API is available in Java.

    • 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
      API:
      This public API is available in Java.

    • lastModified

      public DateTime lastModified()
      Returns the time that the file was last modified.
      Returns:
      last modification timestamp or null.
      API:
      This public API is available in Java.

    • clone

      public File clone()
      Description copied from interface: IIvyDataObject
      Clones the object (shallow clone).
      Specified by:
      clone in interface IIvyDataObject
      Returns:
      A shallow clone.
      API:
      This public API is available in Java.

    • deepClone

      public File deepClone()
      Creates and returns a copy of this object.
      Specified by:
      deepClone in interface IIvyDataObject
      Returns:
      new copy of this object
      API:
      This public API is available in Java.

    • toString

      public String toString()
      API:
      This public API is available in Java.