com.badlogic.gdx.files
Class FileHandle

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

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

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

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