com.codename1.io

Class FileSystemStorage

java.lang.Object

com.codename1.io.FileSystemStorage

public class FileSystemStorage
extends Object

Unlike networking, the file system storage mostly tries to emulate java.io.File with some simplifications for mobile devices.
Check out a more thorough discussion of this API here.
A lot of API's rely on FileSystemStorage as its the API native code usually uses consistently. E.g. in this sample below the FileSystemStorage is used to save a screenshot image for sharing on social media:

The sample below shows the FileSystemStorage as a tree:

Field Summary

Fields

Modifier and Type	Field and Description
static int	ROOT_TYPE_MAINSTORAGE Represents the type for the get root type method, this type generally represents the main phone memory
static int	ROOT_TYPE_SDCARD Represents the type for the get root type method, this type generally represents an SD card although due to variability in phone standards an SD card might be detected incorrectly.
static int	ROOT_TYPE_UNKNOWN Returned for different types of root for which there is no specific knowledge one way or the other.

Method Summary

Modifier and Type	Method and Description
void	delete(String file) Deletes the specific file or empty directory.
void	deleteRetry(String file, int retryCount) Deletes the specific file or empty directory, if the platform supports a delete on exit this method will activate it.
boolean	exists(String file) Indicates whether a file exists
String	getAppHomePath() The application home directory is a "safe place" to store files for this application in a portable way.
String	getCachesDir() Returns a device specific directory designed for cache style files, or null if hasCachesDir() is false
char	getFileSystemSeparator() Returns the file system separator char normally '/'
static FileSystemStorage	getInstance() This class is a singleton
long	getLastModified(String file) Deprecated. this API requires additional privacy permissions on iOS and might cause problems with iOS submissions
long	getLength(String file) Returns the length of the file
long	getRootAvailableSpace(String root) Returns the available space in the given root directory
String[]	getRoots() Returns the filesystem roots from which the structure of the file system can be traversed
long	getRootSizeBytes(String root) Returns the size of the given root directory
int	getRootType(String root) Returns the type of the root often by guessing
boolean	hasCachesDir() Returns true if the device has a directory dedicated for "cache" files
boolean	isDirectory(String file) Indicates whether the given file is a directory
boolean	isHidden(String file) Indicates the hidden state of the file
String[]	listFiles(String directory) Lists the files within the given directory, returns relative file names and not full file names.
void	mkdir(String directory) Creates the given directory
InputStream	openInputStream(String file) Opens an input stream to the given file
OutputStream	openOutputStream(String file) Opens an output stream to the given file
OutputStream	openOutputStream(String file, int offset) Opens an output stream to the given file
void	rename(String file, String newName) Renames a file to the given name, expects the new name to be relative to the current directory
void	setHidden(String file, boolean h) Toggles the hidden state of the file
String	toNativePath(String path) Converts a file system path to a native path.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ROOT_TYPE_MAINSTORAGE

public static final int ROOT_TYPE_MAINSTORAGE

Represents the type for the get root type method, this type generally represents the main phone memory

See Also:

Constant Field Values

ROOT_TYPE_SDCARD

public static final int ROOT_TYPE_SDCARD

Represents the type for the get root type method, this type generally represents an SD card although due to variability in phone standards an SD card might be detected incorrectly. E.g. newer Nokia devices such as N97 have a large storage area that is marked as "E:" but is really internal storage. If an SD card isn't physically in the phone the "F:" won't be returned and it will be impossible to detect that "E:" is not the actual SD card.

See Also:

Constant Field Values

ROOT_TYPE_UNKNOWN

public static final int ROOT_TYPE_UNKNOWN

Returned for different types of root for which there is no specific knowledge one way or the other.

See Also:

Constant Field Values

Method Detail

getInstance

public static FileSystemStorage getInstance()

This class is a singleton

Returns:

instance of this class

getRoots

public String[] getRoots()

Returns the filesystem roots from which the structure of the file system can be traversed

Returns:

the roots of the filesystem

getRootType

public int getRootType(String root)

Returns the type of the root often by guessing

Parameters:

root - the root whose type we are checking

Returns:

one of the type constants above

listFiles

public String[] listFiles(String directory)
                   throws IOException

Lists the files within the given directory, returns relative file names and not full file names.

Parameters:

directory - the directory in which files should be listed

Returns:

array of file names

Throws:

IOException

getRootSizeBytes

public long getRootSizeBytes(String root)

Returns the size of the given root directory

Parameters:

root - the root directory in the filesystem

Returns:

the byte size of the directory

getRootAvailableSpace

public long getRootAvailableSpace(String root)

Returns the available space in the given root directory

Parameters:

root - the root directory in the filesystem

Returns:

the bytes available in the directory

mkdir

public void mkdir(String directory)

Creates the given directory

Parameters:

directory - the directory name to create

delete

public void delete(String file)

Deletes the specific file or empty directory.

Parameters:

file - file or empty directory to delete

deleteRetry

public void deleteRetry(String file,
                        int retryCount)

Deletes the specific file or empty directory, if the platform supports a delete on exit this method will activate it. Regardless it will retry deleting (with delay) several times to allow streams time to close.

Parameters:

file - file to delete

retryCount - the number of times to retry

exists

public boolean exists(String file)

Indicates whether a file exists

Parameters:

file - the file to check

Returns:

true if the file exists and false otherwise

isHidden

public boolean isHidden(String file)

Indicates the hidden state of the file

Parameters:

file - file

Returns:

true for a hidden file

setHidden

public void setHidden(String file,
                      boolean h)

Toggles the hidden state of the file

Parameters:

file - file

h - hidden state

rename

public void rename(String file,
                   String newName)

Renames a file to the given name, expects the new name to be relative to the current directory

Parameters:

file - absolute file name

newName - relative new name

getLength

public long getLength(String file)

Returns the length of the file

Parameters:

file - file

Returns:

length of said file

getLastModified

public long getLastModified(String file)

Deprecated. this API requires additional privacy permissions on iOS and might cause problems with iOS submissions

Returns the time that the file denoted by this abstract pathname was last modified.

Returns:

A long value representing the time the file was last modified, measured in milliseconds

isDirectory

public boolean isDirectory(String file)

Indicates whether the given file is a directory

Parameters:

file - file

Returns:

true if its a directory

getFileSystemSeparator

public char getFileSystemSeparator()

Returns the file system separator char normally '/'

Returns:

the separator char

openOutputStream

public OutputStream openOutputStream(String file)
                              throws IOException

Opens an output stream to the given file

Parameters:

file - the file

Returns:

the output stream

Throws:

IOException

openInputStream

public InputStream openInputStream(String file)
                            throws IOException

Opens an input stream to the given file

Parameters:

file - the file

Returns:

the input stream

Throws:

IOException

openOutputStream

public OutputStream openOutputStream(String file,
                                     int offset)
                              throws IOException

Opens an output stream to the given file

Parameters:

file - the file

offset - position in the file

Returns:

the output stream

Throws:

IOException

getAppHomePath

public String getAppHomePath()

The application home directory is a "safe place" to store files for this application in a portable way. On some platforms such as Android & iOS this path may be visible only to the application itself, other apps won't have permission to access this path.
The sample below uses the app home directory to save a file so we can share it using the ShareButton:

Returns:

a writable directory that represent the application home directory

hasCachesDir

public boolean hasCachesDir()

Returns true if the device has a directory dedicated for "cache" files

Returns:

true if a caches style directory exists in this device type

getCachesDir

public String getCachesDir()

Returns a device specific directory designed for cache style files, or null if hasCachesDir() is false

Returns:

file URL or null

toNativePath

public String toNativePath(String path)

Converts a file system path to a native path.

Parameters:

path - A file system path.

Returns:

The native path.