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:

Serialized Form

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()	Deletes this file or directory.
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 Detail

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 Detail

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

Deletes this file or directory. If this is a directory, it is recursively 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.

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:

isTemporary()

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.