info.guardianproject.iocipher

Class File

java.lang.Object

java.io.File

info.guardianproject.iocipher.File

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<java.io.File>

public class File
extends java.io.File

An "abstract" representation of a file system entity identified by a pathname. The pathname may be absolute (relative to the root directory of the file system) or relative to the current directory in which the program is running.

The actual file referenced by a File may or may not exist. It may also, despite the name File, be a directory or other non-regular file.

This class provides limited functionality for getting/setting file permissions, file type, and last modified time.

On Android strings are converted to UTF-8 byte sequences when sending filenames to the operating system, and byte sequences returned by the operating system (from the various list methods) are converted to strings by decoding them as UTF-8 byte sequences.

See Also:

Serializable, Comparable, Serialized Form

Field Summary

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

Constructors

Constructor and Description
File(java.io.File dir, java.lang.String name) Constructs a new file using the specified directory and name.
File(java.lang.String path) Constructs a new file using the specified path.
File(java.lang.String dirPath, java.lang.String name) Constructs a new File using the specified directory path and file name, placing a path separator between the two.
File(java.net.URI uri) Constructs a new File using the path of the specified URI.

Method Summary

Modifier and Type	Method and Description
boolean	canExecute() Tests whether or not this process is allowed to execute this file.
boolean	canRead() Indicates whether the current context is allowed to read from this file.
boolean	canWrite() Indicates whether the current context is allowed to write to this file.
int	compareTo(File another) Returns the relative sort ordering of the paths for this file and the file another.
boolean	createNewFile() Creates a new, empty file on the file system according to the path information stored in this file.
static File	createTempFile(java.lang.String prefix, java.lang.String suffix) Creates an empty temporary file using the given prefix and suffix as part of the file name.
static File	createTempFile(java.lang.String prefix, java.lang.String suffix, File directory) Creates an empty temporary file in the given directory using the given prefix and suffix as part of the file name.
boolean	delete() Deletes this file.
void	deleteOnExit() Schedules this file to be automatically deleted when the VM terminates normally.
boolean	equals(java.lang.Object obj) Compares obj to this file and returns true if they represent the same object using a path specific comparison.
boolean	exists() Returns a boolean indicating whether this file can be found on the underlying file system.
File	getAbsoluteFile() Returns a new file constructed using the absolute path of this file.
java.lang.String	getAbsolutePath() Returns the absolute path of this file.
File	getCanonicalFile() Returns a new file created using the canonical path of this file.
java.lang.String	getCanonicalPath() Returns the canonical path of this file.
long	getFreeSpace() Returns the number of free bytes on the partition containing this path.
java.lang.String	getName() Returns the name of the file or directory represented by this file.
java.lang.String	getParent() Returns the pathname of the parent of this file.
File	getParentFile() Returns a new file made from the pathname of the parent of this file.
java.lang.String	getPath() Returns the path of this file.
long	getTotalSpace() Returns the total size in bytes of the partition containing this path.
long	getUsableSpace() Returns the number of usable free bytes on the partition containing this path.
int	hashCode() Returns an integer hash code for the receiver.
boolean	isAbsolute() Indicates if this file's pathname is absolute.
boolean	isDirectory() Indicates if this file represents a directory on the underlying file system.
boolean	isFile() Indicates if this file represents a file on the underlying file system.
boolean	isHidden() Returns whether or not this file is a hidden file as defined by the operating system.
long	lastModified() Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight.
long	length() Returns the length of this file in bytes.
java.lang.String[]	list() Returns an array of strings with the file names in the directory represented by this file.
java.lang.String[]	list(FilenameFilter filter) Gets a list of the files in the directory represented by this file.
File[]	listFiles() Returns an array of files contained in the directory represented by this file.
File[]	listFiles(FileFilter filter) Gets a list of the files in the directory represented by this file.
File[]	listFiles(FilenameFilter filter) Gets a list of the files in the directory represented by this file.
boolean	mkdir() Creates the directory named by the trailing filename of this file.
boolean	mkdirs() Creates the directory named by the trailing filename of this file, including the complete directory path required to create this directory.
boolean	renameTo(File newPath) Renames this file to newPath.
boolean	setExecutable(boolean executable) Equivalent to setExecutable(executable, true).
boolean	setExecutable(boolean executable, boolean ownerOnly) Manipulates the execute permissions for the abstract path designated by this file.
boolean	setLastModified(long time) Sets the time this file was last modified, measured in milliseconds since January 1st, 1970, midnight.
boolean	setReadable(boolean readable) Equivalent to setReadable(readable, true).
boolean	setReadable(boolean readable, boolean ownerOnly) Manipulates the read permissions for the abstract path designated by this file.
boolean	setReadOnly() Equivalent to setWritable(false, false).
boolean	setWritable(boolean writable) Equivalent to setWritable(writable, true).
boolean	setWritable(boolean writable, boolean ownerOnly) Manipulates the write permissions for the abstract path designated by this file.
java.lang.String	toString() Returns a string containing a concise, human-readable description of this file.
java.net.URI	toURI() Returns a Uniform Resource Identifier for this file.
java.net.URL	toURL() Deprecated. use toURI() and URI.toURL() to get correct escaping of illegal characters.

Methods inherited from class java.io.File

compareTo, list, listFiles, listFiles, listRoots, renameTo, toPath

Methods inherited from class java.lang.Object

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

Constructor Detail

File

public File(java.io.File dir,
            java.lang.String name)

Constructs a new file using the specified directory and name.

Parameters:

dir - the directory where the file is stored.

name - the file's name.

Throws:

java.lang.NullPointerException - if name is null.

File

public File(java.lang.String path)

Constructs a new file using the specified path.

Parameters:

path - the path to be used for the file.

File

public File(java.lang.String dirPath,
            java.lang.String name)

Constructs a new File using the specified directory path and file name, placing a path separator between the two.

Parameters:

dirPath - the path to the directory where the file is stored.

name - the file's name.

Throws:

java.lang.NullPointerException - if name == null.

File

public File(java.net.URI uri)

Constructs a new File using the path of the specified URI. uri needs to be an absolute and hierarchical Unified Resource Identifier with file scheme and non-empty path component, but with undefined authority, query or fragment components.

Parameters:

uri - the Unified Resource Identifier that is used to construct this file.

Throws:

java.lang.IllegalArgumentException - if uri does not comply with the conditions above.

See Also:

toURI(), URI

Method Detail

canExecute

public boolean canExecute()

Tests whether or not this process is allowed to execute this file. Note that this is a best-effort result; the only way to be certain is to actually attempt the operation.

Overrides:

canExecute in class java.io.File

Returns:

true if this file can be executed, false otherwise.

Since:

1.6

canRead

public boolean canRead()

Indicates whether the current context is allowed to read from this file.

Overrides:

canRead in class java.io.File

Returns:

true if this file can be read, false otherwise.

canWrite

public boolean canWrite()

Indicates whether the current context is allowed to write to this file.

Overrides:

canWrite in class java.io.File

Returns:

true if this file can be written, false otherwise.

compareTo

public int compareTo(File another)

Returns the relative sort ordering of the paths for this file and the file another. The ordering is platform dependent.

Parameters:

another - a file to compare this file to

Returns:

an int determined by comparing the two paths. Possible values are described in the Comparable interface.

See Also:

Comparable

delete

public boolean delete()

Deletes this file. Directories must be empty before they will be deleted.

Note that this method does not throw IOException on failure. Callers must check the return value.

Overrides:

delete in class java.io.File

Returns:

true if this file was deleted, false otherwise.

deleteOnExit

public void deleteOnExit()
                  throws java.lang.UnsupportedOperationException

Schedules this file to be automatically deleted when the VM terminates normally.

Note that on Android, the application lifecycle does not include VM termination, so calling this method will not ensure that files are deleted. Instead, you should use the most appropriate out of:

• Use a finally clause to manually invoke delete().
• Maintain your own set of files to delete, and process it at an appropriate point in your application's lifecycle.
• Use the Unix trick of deleting the file as soon as all readers and writers have opened it. No new readers/writers will be able to access the file, but all existing ones will still have access until the last one closes the file.

Overrides:

deleteOnExit in class java.io.File

Throws:

java.lang.UnsupportedOperationException

equals

public boolean equals(java.lang.Object obj)

Compares obj to this file and returns true if they represent the same object using a path specific comparison.

Overrides:

equals in class java.io.File

Parameters:

obj - the object to compare this file with.

Returns:

true if obj is the same as this object, false otherwise.

exists

public boolean exists()

Returns a boolean indicating whether this file can be found on the underlying file system.

Overrides:

exists in class java.io.File

Returns:

true if this file exists, false otherwise.

getAbsolutePath

public java.lang.String getAbsolutePath()

Returns the absolute path of this file. An absolute path is a path that starts at a root of the file system. On Android, there is only one root: /.

A common use for absolute paths is when passing paths to a Process as command-line arguments, to remove the requirement implied by relative paths, that the child must have the same working directory as its parent.

Overrides:

getAbsolutePath in class java.io.File

getAbsoluteFile

public File getAbsoluteFile()

Returns a new file constructed using the absolute path of this file. Equivalent to new File(this.getAbsolutePath()).

Overrides:

getAbsoluteFile in class java.io.File

getCanonicalPath

public java.lang.String getCanonicalPath()
                                  throws java.io.IOException

Returns the canonical path of this file. An absolute path is one that begins at the root of the file system. A canonical path is an absolute path with symbolic links and references to "." or ".." resolved. If a path element does not exist (or is not searchable), there is a conflict between interpreting canonicalization as a textual operation (where "a/../b" is "b" even if "a" does not exist) .

Most callers should use getAbsolutePath() instead. A canonical path is significantly more expensive to compute, and not generally useful. The primary use for canonical paths is determining whether two paths point to the same file by comparing the canonicalized paths.

It can be actively harmful to use a canonical path, specifically because canonicalization removes symbolic links. It's wise to assume that a symbolic link is present for a reason, and that that reason is because the link may need to change. Canonicalization removes this layer of indirection. Good code should generally avoid caching canonical paths.

Overrides:

getCanonicalPath in class java.io.File

Returns:

the canonical path of this file.

Throws:

java.io.IOException - if an I/O error occurs.

getCanonicalFile

public File getCanonicalFile()
                      throws java.io.IOException

Returns a new file created using the canonical path of this file. Equivalent to new File(this.getCanonicalPath()).

Overrides:

getCanonicalFile in class java.io.File

Returns:

the new file constructed from this file's canonical path.

Throws:

java.io.IOException - if an I/O error occurs.

getName

public java.lang.String getName()

Returns the name of the file or directory represented by this file.

Overrides:

getName in class java.io.File

Returns:

this file's name or an empty string if there is no name part in the file's path.

getParent

public java.lang.String getParent()

Returns the pathname of the parent of this file. This is the path up to but not including the last name. null is returned if there is no parent.

Overrides:

getParent in class java.io.File

Returns:

this file's parent pathname or null.

getParentFile

public File getParentFile()

Returns a new file made from the pathname of the parent of this file. This is the path up to but not including the last name. null is returned when there is no parent.

Overrides:

getParentFile in class java.io.File

Returns:

a new file representing this file's parent or null.

getPath

public java.lang.String getPath()

Returns the path of this file.

Overrides:

getPath in class java.io.File

Returns:

this file's path.

hashCode

public int hashCode()

Returns an integer hash code for the receiver. Any two objects for which equals returns true must return the same hash code.

Overrides:

hashCode in class java.io.File

Returns:

this files's hash value.

See Also:

equals(java.lang.Object)

isAbsolute

public boolean isAbsolute()

Indicates if this file's pathname is absolute. Whether a pathname is absolute is platform specific. On Android, absolute paths start with the character '/'.

Overrides:

isAbsolute in class java.io.File

Returns:

true if this file's pathname is absolute, false otherwise.

See Also:

getPath()

isDirectory

public boolean isDirectory()

Indicates if this file represents a directory on the underlying file system.

Overrides:

isDirectory in class java.io.File

Returns:

true if this file is a directory, false otherwise.

isFile

public boolean isFile()

Indicates if this file represents a file on the underlying file system.

Overrides:

isFile in class java.io.File

Returns:

true if this file is a file, false otherwise.

isHidden

public boolean isHidden()

Returns whether or not this file is a hidden file as defined by the operating system. The notion of "hidden" is system-dependent. For Unix systems a file is considered hidden if its name starts with a ".". For Windows systems there is an explicit flag in the file system for this purpose.

Overrides:

isHidden in class java.io.File

Returns:

true if the file is hidden, false otherwise.

lastModified

public long lastModified()

Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight. Returns 0 if the file does not exist.

Overrides:

lastModified in class java.io.File

Returns:

the time when this file was last modified.

setLastModified

public boolean setLastModified(long time)

Sets the time this file was last modified, measured in milliseconds since January 1st, 1970, midnight.

Note that this method does not throw IOException on failure. Callers must check the return value.

Overrides:

setLastModified in class java.io.File

Parameters:

time - the last modification time for this file.

Returns:

true if the operation is successful, false otherwise.

Throws:

java.lang.IllegalArgumentException - if time < 0.

setReadOnly

public boolean setReadOnly()

Equivalent to setWritable(false, false).

Overrides:

setReadOnly in class java.io.File

See Also:

setWritable(boolean, boolean)

setExecutable

public boolean setExecutable(boolean executable,
                             boolean ownerOnly)

Manipulates the execute permissions for the abstract path designated by this file.

Note that this method does not throw IOException on failure. Callers must check the return value.

Overrides:

setExecutable in class java.io.File

Parameters:

executable - To allow execute permission if true, otherwise disallow

ownerOnly - To manipulate execute permission only for owner if true, otherwise for everyone. The manipulation will apply to everyone regardless of this value if the underlying system does not distinguish owner and other users.

Returns:

true if and only if the operation succeeded. If the user does not have permission to change the access permissions of this abstract pathname the operation will fail. If the underlying file system does not support execute permission and the value of executable is false, this operation will fail.

Since:

1.6

setExecutable

public boolean setExecutable(boolean executable)

Equivalent to setExecutable(executable, true).

Overrides:

setExecutable in class java.io.File

Since:

1.6

See Also:

setExecutable(boolean, boolean)

setReadable

public boolean setReadable(boolean readable,
                           boolean ownerOnly)

Manipulates the read permissions for the abstract path designated by this file.

Overrides:

setReadable in class java.io.File

Parameters:

readable - To allow read permission if true, otherwise disallow

ownerOnly - To manipulate read permission only for owner if true, otherwise for everyone. The manipulation will apply to everyone regardless of this value if the underlying system does not distinguish owner and other users.

Returns:

true if and only if the operation succeeded. If the user does not have permission to change the access permissions of this abstract pathname the operation will fail. If the underlying file system does not support read permission and the value of readable is false, this operation will fail.

Since:

1.6

setReadable

public boolean setReadable(boolean readable)

Equivalent to setReadable(readable, true).

Overrides:

setReadable in class java.io.File

Since:

1.6

See Also:

setReadable(boolean, boolean)

setWritable

public boolean setWritable(boolean writable,
                           boolean ownerOnly)

Manipulates the write permissions for the abstract path designated by this file.

Overrides:

setWritable in class java.io.File

Parameters:

writable - To allow write permission if true, otherwise disallow

ownerOnly - To manipulate write permission only for owner if true, otherwise for everyone. The manipulation will apply to everyone regardless of this value if the underlying system does not distinguish owner and other users.

Returns:

true if and only if the operation succeeded. If the user does not have permission to change the access permissions of this abstract pathname the operation will fail.

Since:

1.6

setWritable

public boolean setWritable(boolean writable)

Equivalent to setWritable(writable, true).

Overrides:

setWritable in class java.io.File

Since:

1.6

See Also:

setWritable(boolean, boolean)

length

public long length()

Returns the length of this file in bytes. Returns 0 if the file does not exist. The result for a directory is not defined.

Overrides:

length in class java.io.File

Returns:

the number of bytes in this file.

list

public java.lang.String[] list()

Returns an array of strings with the file names in the directory represented by this file. The result is null if this file is not a directory.

The entries . and .. representing the current and parent directory are not returned as part of the list.

Overrides:

list in class java.io.File

Returns:

an array of strings with file names or null.

list

public java.lang.String[] list(FilenameFilter filter)

Gets a list of the files in the directory represented by this file. This list is then filtered through a FilenameFilter and the names of files with matching names are returned as an array of strings. Returns null if this file is not a directory. If filter is null then all filenames match.

The entries . and .. representing the current and parent directories are not returned as part of the list.

Parameters:

filter - the filter to match names against, may be null.

Returns:

an array of files or null.

listFiles

public File[] listFiles()

Returns an array of files contained in the directory represented by this file. The result is null if this file is not a directory. The paths of the files in the array are absolute if the path of this file is absolute, they are relative otherwise.

Overrides:

listFiles in class java.io.File

Returns:

an array of files or null.

listFiles

public File[] listFiles(FilenameFilter filter)

Gets a list of the files in the directory represented by this file. This list is then filtered through a FilenameFilter and files with matching names are returned as an array of files. Returns null if this file is not a directory. If filter is null then all filenames match.

The entries . and .. representing the current and parent directories are not returned as part of the list.

Parameters:

filter - the filter to match names against, may be null.

Returns:

an array of files or null.

listFiles

public File[] listFiles(FileFilter filter)

Gets a list of the files in the directory represented by this file. This list is then filtered through a FileFilter and matching files are returned as an array of files. Returns null if this file is not a directory. If filter is null then all files match.

The entries . and .. representing the current and parent directories are not returned as part of the list.

Parameters:

filter - the filter to match names against, may be null.

Returns:

an array of files or null.

mkdir

public boolean mkdir()

Creates the directory named by the trailing filename of this file. Does not create the complete path required to create this directory.

Note that this method does not throw IOException on failure. Callers must check the return value.

Overrides:

mkdir in class java.io.File

Returns:

true if the directory has been created, false otherwise.

See Also:

mkdirs()

mkdirs

public boolean mkdirs()

Creates the directory named by the trailing filename of this file, including the complete directory path required to create this directory.

Note that this method does not throw IOException on failure. Callers must check the return value.

Overrides:

mkdirs in class java.io.File

Returns:

true if the necessary directories have been created, false if the target directory already exists or one of the directories can not be created.

See Also:

mkdir()

createNewFile

public boolean createNewFile()
                      throws java.io.IOException

Creates a new, empty file on the file system according to the path information stored in this file. This method returns true if it creates a file, false if the file already existed. Note that it returns false even if the file is not a file (because it's a directory, say).

This method is not generally useful. For creating temporary files, use createTempFile(java.lang.String, java.lang.String) instead. For reading/writing files, use FileInputStream, FileOutputStream, or RandomAccessFile, all of which can create files.

Note that this method does not throw IOException if the file already exists, even if it's not a regular file. Callers should always check the return value, and may additionally want to call isFile().

Overrides:

createNewFile in class java.io.File

Returns:

true if the file has been created, false if it already exists.

Throws:

java.io.IOException - if it's not possible to create the file.

createTempFile

public static File createTempFile(java.lang.String prefix,
                                  java.lang.String suffix)
                           throws java.io.IOException

Creates an empty temporary file using the given prefix and suffix as part of the file name. If suffix is null, .tmp is used. This method is a convenience method that calls createTempFile(String, String, File) with the third argument being null.

Parameters:

prefix - the prefix to the temp file name.

suffix - the suffix to the temp file name.

Returns:

the temporary file.

Throws:

java.io.IOException - if an error occurs when writing the file.

createTempFile

public static File createTempFile(java.lang.String prefix,
                                  java.lang.String suffix,
                                  File directory)
                           throws java.io.IOException

Creates an empty temporary file in the given directory using the given prefix and suffix as part of the file name. If suffix is null, .tmp is used.

Note that this method does not call deleteOnExit(), but see the documentation for that method before you call it manually.

Parameters:

prefix - the prefix to the temp file name.

suffix - the suffix to the temp file name.

directory - the location to which the temp file is to be written, or null for the default location for temporary files, which is taken from the "java.io.tmpdir" system property. It may be necessary to set this property to an existing, writable directory for this method to work properly.

Returns:

the temporary file.

Throws:

java.lang.IllegalArgumentException - if the length of prefix is less than 3.

java.io.IOException - if an error occurs when writing the file.

renameTo

public boolean renameTo(File newPath)

Renames this file to newPath. This operation is supported for both files and directories.

Many failures are possible. Some of the more likely failures include:

• Write permission is required on the directories containing both the source and destination paths.
• Search permission is required for all parents of both paths.
• Both paths be on the same mount point. On Android, applications are most likely to hit this restriction when attempting to copy between internal storage and an SD card.

Note that this method does not throw IOException on failure. Callers must check the return value.

Parameters:

newPath - the new path.

Returns:

true on success.

toString

public java.lang.String toString()

Returns a string containing a concise, human-readable description of this file.

Overrides:

toString in class java.io.File

Returns:

a printable representation of this file.

toURI

public java.net.URI toURI()

Returns a Uniform Resource Identifier for this file. The URI is system dependent and may not be transferable between different operating / file systems.

Overrides:

toURI in class java.io.File

Returns:

an URI for this file.

toURL

@Deprecated
public java.net.URL toURL()
                               throws java.net.MalformedURLException

Deprecated. use toURI() and URI.toURL() to get correct escaping of illegal characters.

Returns a Uniform Resource Locator for this file. The URL is system dependent and may not be transferable between different operating / file systems.

Overrides:

toURL in class java.io.File

Returns:

a URL for this file.

Throws:

java.net.MalformedURLException - if the path cannot be transformed into a URL.

getTotalSpace

public long getTotalSpace()

Returns the total size in bytes of the partition containing this path. Returns 0 if this path does not exist.

Overrides:

getTotalSpace in class java.io.File

Since:

1.6

getUsableSpace

public long getUsableSpace()

Returns the number of usable free bytes on the partition containing this path. Returns 0 if this path does not exist.

Note that this is likely to be an optimistic over-estimate and should not be taken as a guarantee your application can actually write this many bytes. On Android (and other Unix-based systems), this method returns the number of free bytes available to non-root users, regardless of whether you're actually running as root, and regardless of any quota or other restrictions that might apply to the user. (The getFreeSpace method returns the number of bytes potentially available to root.)

Overrides:

getUsableSpace in class java.io.File

Since:

1.6

getFreeSpace

public long getFreeSpace()

Returns the number of free bytes on the partition containing this path. Returns 0 if this path does not exist.

Note that this is likely to be an optimistic over-estimate and should not be taken as a guarantee your application can actually write this many bytes.

Overrides:

getFreeSpace in class java.io.File

Since:

1.6