FileHandle (libGDX Core 1.2.0 API)

java.lang.Object
- com.badlogic.gdx.files.FileHandle

Direct Known Subclasses:

FileHandleStream
```
public class FileHandle
extends Object
```
Represents a file or directory on the filesystem, classpath, Android SD card, or Android assets directory. FileHandles are created via a Files instance. Because some of the file types are backed by composite files and may be compressed (for example, if they are in an Android .apk or are found via the classpath), the methods for extracting a path() or file() may not be appropriate for all types. Use the Reader or Stream methods here to hide these dependencies from your platform independent code.

Author:

mzechner, Nathan Sweet

Constructor Summary

Constructors
Constructor and Description
`FileHandle(File file)` Creates a new absolute FileHandle for the `File`.
`FileHandle(String fileName)` Creates a new absolute FileHandle for the file name.

Method Summary

Methods
Modifier and Type	Method and Description
`FileHandle`	`child(String name)` Returns a handle to the child with the specified name.
`void`	`copyTo(FileHandle dest)` Copies this file or directory to the specified file or directory.
`boolean`	`delete()` Deletes this file or empty directory and returns success.
`boolean`	`deleteDirectory()` Deletes this file or directory and all children, recursively.
`void`	`emptyDirectory()` Deletes all children of this directory, recursively.
`void`	`emptyDirectory(boolean preserveTree)` Deletes all children of this directory, recursively.
`boolean`	`equals(Object obj)`
`boolean`	`exists()` Returns true if the file exists.
`String`	`extension()`
`File`	`file()` Returns a java.io.File that represents this file handle.
`int`	`hashCode()`
`boolean`	`isDirectory()` Returns true if this file is a directory.
`long`	`lastModified()` Returns the last modified time in milliseconds for this file.
`long`	`length()` Returns the length in bytes of this file, or 0 if this file is a directory, does not exist, or the size cannot otherwise be determined.
`FileHandle[]`	`list()` Returns the paths to the children of this directory.
`FileHandle[]`	`list(FileFilter filter)` Returns the paths to the children of this directory that satisfy the specified filter.
`FileHandle[]`	`list(FilenameFilter filter)` Returns the paths to the children of this directory that satisfy the specified filter.
`FileHandle[]`	`list(String suffix)` Returns the paths to the children of this directory with the specified suffix.
`void`	`mkdirs()`
`void`	`moveTo(FileHandle dest)` Moves this file to the specified file, overwriting the file if it already exists.
`String`	`name()`
`String`	`nameWithoutExtension()`
`FileHandle`	`parent()`
`String`	`path()`
`String`	`pathWithoutExtension()`
`InputStream`	`read()` Returns a stream for reading this file as bytes.
`BufferedInputStream`	`read(int bufferSize)` Returns a buffered stream for reading this file as bytes.
`byte[]`	`readBytes()` Reads the entire file into a byte array.
`int`	`readBytes(byte[] bytes, int offset, int size)` Reads the entire file into the byte array.
`Reader`	`reader()` Returns a reader for reading this file as characters.
`BufferedReader`	`reader(int bufferSize)` Returns a buffered reader for reading this file as characters.
`BufferedReader`	`reader(int bufferSize, String charset)` Returns a buffered reader for reading this file as characters.
`Reader`	`reader(String charset)` Returns a reader for reading this file as characters.
`String`	`readString()` Reads the entire file into a string using the platform's default charset.
`String`	`readString(String charset)` Reads the entire file into a string using the specified charset.
`FileHandle`	`sibling(String name)` Returns a handle to the sibling with the specified name.
`static FileHandle`	`tempDirectory(String prefix)`
`static FileHandle`	`tempFile(String prefix)`
`String`	`toString()`
`Files.FileType`	`type()`
`OutputStream`	`write(boolean append)` Returns a stream for writing to this file.
`OutputStream`	`write(boolean append, int bufferSize)` Returns a buffered stream for writing to this file.
`void`	`write(InputStream input, boolean append)` Reads the remaining bytes from the specified stream and writes them to this file.
`void`	`writeBytes(byte[] bytes, boolean append)` Writes the specified bytes to the file.
`void`	`writeBytes(byte[] bytes, int offset, int length, boolean append)` Writes the specified bytes to the file.
`Writer`	`writer(boolean append)` Returns a writer for writing to this file using the default charset.
`Writer`	`writer(boolean append, String charset)` Returns a writer for writing to this file.
`void`	`writeString(String string, boolean append)` Writes the specified string to the file using the default charset.
`void`	`writeString(String string, boolean append, String charset)` Writes the specified string to the file as UTF-8.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - FileHandle
```
public FileHandle(String fileName)
```
    Creates a new absolute FileHandle for the file name. Use this for tools on the desktop that don't need any of the backends. Do not use this constructor in case you write something cross-platform. Use the Files interface instead.
    
    Parameters:
    fileName - the filename.
  - FileHandle
```
public FileHandle(File file)
```
    Creates a new absolute FileHandle for the File. Use this for tools on the desktop that don't need any of the backends. Do not use this constructor in case you write something cross-platform. Use the Files interface instead.
    
    Parameters:
    file - the file.
- Method Detail
  - path
```
public String path()
```
    Returns:
    the path of the file as specified on construction, e.g. Gdx.files.internal("dir/file.png") -> dir/file.png. backward slashes will be replaced by forward slashes.
  - name
```
public String name()
```
    Returns:
    the name of the file, without any parent paths.
  - extension
```
public String extension()
```
  - nameWithoutExtension
```
public String nameWithoutExtension()
```
    Returns:
    the name of the file, without parent paths or the extension.
  - pathWithoutExtension
```
public String pathWithoutExtension()
```
    Returns:
    the path and filename without the extension, e.g. dir/dir2/file.png -> dir/dir2/file. backward slashes will be returned as forward slashes.
  - type
```
public Files.FileType type()
```
  - file
```
public File file()
```
    Returns a java.io.File that represents this file handle. Note the returned file will only be usable for Files.FileType.Absolute and Files.FileType.External file handles.
  - read
```
public InputStream read()
```
    Returns a stream for reading this file as bytes.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - read
```
public BufferedInputStream read(int bufferSize)
```
    Returns a buffered stream for reading this file as bytes.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - reader
```
public Reader reader()
```
    Returns a reader for reading this file as characters.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - reader
```
public Reader reader(String charset)
```
    Returns a reader for reading this file as characters.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - reader
```
public BufferedReader reader(int bufferSize)
```
    Returns a buffered reader for reading this file as characters.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - reader
```
public BufferedReader reader(int bufferSize,
                    String charset)
```
    Returns a buffered reader for reading this file as characters.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - readString
```
public String readString()
```
    Reads the entire file into a string using the platform's default charset.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - readString
```
public String readString(String charset)
```
    Reads the entire file into a string using the specified charset.
    
    Parameters:
    charset - If null the default charset is used.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - readBytes
```
public byte[] readBytes()
```
    Reads the entire file into a byte array.
    
    Throws:
    
    GdxRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.
  - readBytes
```
public int readBytes(byte[] bytes,
            int offset,
            int size)
```
    Reads the entire file into the byte array. The byte array must be big enough to hold the file's data.
    
    Parameters:
    bytes - the array to load the file into
    offset - the offset to start writing bytes
    size - the number of bytes to read, see length()
    
    Returns:
    the number of read bytes
  - write
```
public OutputStream write(boolean append)
```
    Returns a stream for writing to this file. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - write
```
public OutputStream write(boolean append,
                 int bufferSize)
```
    Returns a buffered stream for writing to this file. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    bufferSize - The size of the buffer.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - write
```
public void write(InputStream input,
         boolean append)
```
    Reads the remaining bytes from the specified stream and writes them to this file. The stream is closed. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - writer
```
public Writer writer(boolean append)
```
    Returns a writer for writing to this file using the default charset. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - writer
```
public Writer writer(boolean append,
            String charset)
```
    Returns a writer for writing to this file. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    charset - May be null to use the default charset.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - writeString
```
public void writeString(String string,
               boolean append)
```
    Writes the specified string to the file using the default charset. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - writeString
```
public void writeString(String string,
               boolean append,
               String charset)
```
    Writes the specified string to the file as UTF-8. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    charset - May be null to use the default charset.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - writeBytes
```
public void writeBytes(byte[] bytes,
              boolean append)
```
    Writes the specified bytes to the file. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - writeBytes
```
public void writeBytes(byte[] bytes,
              int offset,
              int length,
              boolean append)
```
    Writes the specified bytes to the file. Parent directories will be created if necessary.
    
    Parameters:
    append - If false, this file will be overwritten if it exists, otherwise it will be appended.
    
    Throws:
    
    GdxRuntimeException - if this file handle represents a directory, if it is a Files.FileType.Classpath or Files.FileType.Internal file, or if it could not be written.
  - list
```
public FileHandle[] list()
```
    Returns the paths to the children of this directory. Returns an empty list if this file handle represents a file and not a directory. On the desktop, an Files.FileType.Internal handle to a directory on the classpath will return a zero length array.
    
    Throws:
    
    GdxRuntimeException - if this file is an Files.FileType.Classpath file.
  - list
```
public FileHandle[] list(FileFilter filter)
```
    Returns the paths to the children of this directory that satisfy the specified filter. Returns an empty list if this file handle represents a file and not a directory. On the desktop, an Files.FileType.Internal handle to a directory on the classpath will return a zero length array.
    
    Parameters:
    filter - the FileFilter to filter files
    
    Throws:
    
    GdxRuntimeException - if this file is an Files.FileType.Classpath file.
  - list
```
public FileHandle[] list(FilenameFilter filter)
```
    Returns the paths to the children of this directory that satisfy the specified filter. Returns an empty list if this file handle represents a file and not a directory. On the desktop, an Files.FileType.Internal handle to a directory on the classpath will return a zero length array.
    
    Parameters:
    filter - the FilenameFilter to filter files
    
    Throws:
    
    GdxRuntimeException - if this file is an Files.FileType.Classpath file.
  - list
```
public FileHandle[] list(String suffix)
```
    Returns the paths to the children of this directory with the specified suffix. Returns an empty list if this file handle represents a file and not a directory. On the desktop, an Files.FileType.Internal handle to a directory on the classpath will return a zero length array.
    
    Throws:
    
    GdxRuntimeException - if this file is an Files.FileType.Classpath file.
  - isDirectory
```
public boolean isDirectory()
```
    Returns true if this file is a directory. Always returns false for classpath files. On Android, an Files.FileType.Internal handle to an empty directory will return false. On the desktop, an Files.FileType.Internal handle to a directory on the classpath will return false.
  - child
```
public FileHandle child(String name)
```
    Returns a handle to the child with the specified name.
    
    Throws:
    
    GdxRuntimeException - if this file handle is a Files.FileType.Classpath or Files.FileType.Internal and the child doesn't exist.
  - sibling
```
public FileHandle sibling(String name)
```
    Returns a handle to the sibling with the specified name.
    
    Throws:
    
    GdxRuntimeException - if this file handle is a Files.FileType.Classpath or Files.FileType.Internal and the sibling doesn't exist, or this file is the root.
  - parent
```
public FileHandle parent()
```
  - mkdirs
```
public void mkdirs()
```
    Throws:
    
    GdxRuntimeException - if this file handle is a Files.FileType.Classpath or Files.FileType.Internal file.
  - exists
```
public boolean exists()
```
    Returns true if the file exists. On Android, a Files.FileType.Classpath or Files.FileType.Internal handle to a directory will always return false. Note that this can be very slow for internal files on Android!
  - delete
```
public boolean delete()
```
    Deletes this file or empty directory and returns success. Will not delete a directory that has children.
    
    Throws:
    
    GdxRuntimeException - if this file handle is a Files.FileType.Classpath or Files.FileType.Internal file.
  - deleteDirectory
```
public boolean deleteDirectory()
```
    Deletes this file or directory and all children, recursively.
    
    Throws:
    
    GdxRuntimeException - if this file handle is a Files.FileType.Classpath or Files.FileType.Internal file.
  - emptyDirectory
```
public void emptyDirectory()
```
    Deletes all children of this directory, recursively.
    
    Throws:
    
    GdxRuntimeException - if this file handle is a Files.FileType.Classpath or Files.FileType.Internal file.
  - emptyDirectory
```
public void emptyDirectory(boolean preserveTree)
```
    Deletes all children of this directory, recursively. Optionally preserving the folder structure.
    
    Throws:
    
    GdxRuntimeException - if this file handle is a Files.FileType.Classpath or Files.FileType.Internal file.
  - copyTo
```
public void copyTo(FileHandle dest)
```
    Copies this file or directory to the specified file or directory. If this handle is a file, then 1) if the destination is a file, it is overwritten, or 2) if the destination is a directory, this file is copied into it, or 3) if the destination doesn't exist, mkdirs() is called on the destination's parent and this file is copied into it with a new name. If this handle is a directory, then 1) if the destination is a file, GdxRuntimeException is thrown, or 2) if the destination is a directory, this directory is copied into it recursively, overwriting existing files, or 3) if the destination doesn't exist, mkdirs() is called on the destination and this directory is copied into it recursively.
    
    Throws:
    
    GdxRuntimeException - if the destination file handle is a Files.FileType.Classpath or Files.FileType.Internal file, or copying failed.
  - moveTo
```
public void moveTo(FileHandle dest)
```
    Moves this file to the specified file, overwriting the file if it already exists.
    
    Throws:
    
    GdxRuntimeException - if the source or destination file handle is a Files.FileType.Classpath or Files.FileType.Internal file.
  - length
```
public long length()
```
    Returns the length in bytes of this file, or 0 if this file is a directory, does not exist, or the size cannot otherwise be determined.
  - lastModified
```
public long lastModified()
```
    Returns the last modified time in milliseconds for this file. Zero is returned if the file doesn't exist. Zero is returned for Files.FileType.Classpath files. On Android, zero is returned for Files.FileType.Internal files. On the desktop, zero is returned for Files.FileType.Internal files on the classpath.
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - tempFile
```
public static FileHandle tempFile(String prefix)
```
  - tempDirectory
```
public static FileHandle tempDirectory(String prefix)
```

Class FileHandle

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

FileHandle

FileHandle

Method Detail

path

name

extension

nameWithoutExtension

pathWithoutExtension

type

file

read

read

reader

reader

reader

reader

readString

readString

readBytes

readBytes

write

write

write

writer

writer

writeString

writeString

writeBytes

writeBytes

list

list

list

list

isDirectory

child

sibling

parent

mkdirs

exists

delete

deleteDirectory

emptyDirectory

emptyDirectory

copyTo

moveTo

length

lastModified

equals

hashCode

toString

tempFile

tempDirectory