public final class FileSystemStorage

  1. Object
  2. FileSystemStorage

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:

Form hi = new Form("ShareButton");
ShareButton sb = new ShareButton();
sb.setText("Share Screenshot");
hi.add(sb);

Image screenshot = Image.createImage(hi.getWidth(), hi.getHeight());
hi.revalidate();
hi.setVisible(true);
hi.paintComponent(screenshot.getGraphics(), true);

String imageFile = FileSystemStorage.getInstance().getAppHomePath() + "screenshot.png";
try(OutputStream os = FileSystemStorage.getInstance().openOutputStream(imageFile)) {
    ImageIO.getImageIO().save(screenshot, os, ImageIO.FORMAT_PNG, 1);
} catch(IOException err) {
    Log.e(err);
}
sb.setImageToShare(imageFile, "image/png");

The sample below shows the FileSystemStorage as a tree:

Form hi = new Form("FileSystemTree", new BorderLayout());
TreeModel tm = new TreeModel() {
@Override
    public Vector getChildren(Object parent) {
        String[] files;
        if(parent == null) {
            files = FileSystemStorage.getInstance().getRoots();
            return new Vector(Arrays.asList(files));
        } else {
            try {
                files = FileSystemStorage.getInstance().listFiles((String)parent);
            } catch(IOException err) {
                Log.e(err);
                files = new String[0];
            }
        }
        String p = (String)parent;
        Vector result = new Vector();
        for(String s : files) {
            result.add(p + s);
        }
        return result;
    }
@Override
    public boolean isLeaf(Object node) {
        return !FileSystemStorage.getInstance().isDirectory((String)node);
    }
};
Tree t = new Tree(tm) {
@Override
    protected String childToDisplayLabel(Object child) {
        String n = (String)child;
        int pos = n.lastIndexOf("/");
        if(pos
@author Shai Almog

Fields

public static final int ROOT_TYPE_MAINSTORAGE = 1Represents the type for the get root type method, this type generally represents the main phone memory
public static final int ROOT_TYPE_SDCARD = 2Represents 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.
public static final int ROOT_TYPE_UNKNOWN = 3Returned for different types of root for which there is no specific knowledge one way or the other.

Methods

public static FileSystemStorage getInstance()This class is a singleton
public String[] getRoots()Returns the filesystem roots from which the structure of the file system can be traversed
public int getRootType(String root)Returns the type of the root often by guessing
public String[] listFiles(String directory) throws IOExceptionLists the files within the given directory, returns relative file names and not full file names.
public long getRootSizeBytes(String root)Returns the size of the given root directory
public long getRootAvailableSpace(String root)Returns the available space in the given root directory
public void mkdir(String directory)Creates the given directory
public void delete(String file)Deletes the specific file or empty directory.
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.
public boolean exists(String file)Indicates whether a file exists
public boolean isHidden(String file)Indicates the hidden state of the file
public void setHidden(String file, boolean h)Toggles the hidden state of the file
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
public long getLength(String file)Returns the length of the file
public long getLastModified(String file)Deprecated Returns the time that the file denoted by this abstract pathname was last modified.
public boolean isDirectory(String file)Indicates whether the given file is a directory
public char getFileSystemSeparator()Returns the file system separator char normally ‘/’
public OutputStream openOutputStream(String file) throws IOExceptionOpens an output stream to the given file
public InputStream openInputStream(String file) throws IOExceptionOpens an input stream to the given file
public OutputStream openOutputStream(String file, int offset) throws IOExceptionOpens an output stream to the given file
public String getAppHomePath()The application home directory is a “safe place” to store files for this application in a portable way.
public boolean hasCachesDir()Returns true if the device has a directory dedicated for “cache” files
public String getCachesDir()Returns a device specific directory designed for cache style files, or null if #hasCachesDir() is false
public String toNativePath(String path)Converts a file system path to a native path.

Inherited methods

Field details

ROOT_TYPE_MAINSTORAGE

public static final int ROOT_TYPE_MAINSTORAGE = 1
Represents the type for the get root type method, this type generally represents the main phone memory

ROOT_TYPE_SDCARD

public static final int ROOT_TYPE_SDCARD = 2
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.

ROOT_TYPE_UNKNOWN

public static final int ROOT_TYPE_UNKNOWN = 3
Returned for different types of root for which there is no specific knowledge one way or the other.

Method details

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 String
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 String
the directory in which files should be listed

Returns

array of file names

getRootSizeBytes

public long getRootSizeBytes(String root)
Returns the size of the given root directory

Parameters

root String
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 String
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 String
the directory name to create

delete

public void delete(String file)
Deletes the specific file or empty directory.

Parameters

file String
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 String
file to delete
retryCount int
the number of times to retry

exists

public boolean exists(String file)
Indicates whether a file exists

Parameters

file String
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 String
file

Returns

true for a hidden file

setHidden

public void setHidden(String file, boolean h)
Toggles the hidden state of the file

Parameters

file String
file
h boolean
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 String
absolute file name
newName String
relative new name

getLength

public long getLength(String file)
Returns the length of the file

Parameters

file String
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 String
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 String
the file

Returns

the output stream

openInputStream

public InputStream openInputStream(String file) throws IOException
Opens an input stream to the given file

Parameters

file String
the file

Returns

the input stream

openOutputStream

public OutputStream openOutputStream(String file, int offset) throws IOException
Opens an output stream to the given file

Parameters

file String
the file
offset int
position in the file

Returns

the output stream

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 com.codename1.components.ShareButton:

Form hi = new Form("ShareButton");
ShareButton sb = new ShareButton();
sb.setText("Share Screenshot");
hi.add(sb);

Image screenshot = Image.createImage(hi.getWidth(), hi.getHeight());
hi.revalidate();
hi.setVisible(true);
hi.paintComponent(screenshot.getGraphics(), true);

String imageFile = FileSystemStorage.getInstance().getAppHomePath() + "screenshot.png";
try(OutputStream os = FileSystemStorage.getInstance().openOutputStream(imageFile)) {
ImageIO.getImageIO().save(screenshot, os, ImageIO.FORMAT_PNG, 1);
} catch(IOException err) {
Log.e(err);
}
sb.setImageToShare(imageFile, "image/png");

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 String
A file system path.

Returns

The native path.