# Class FileSystemStorage

java.lang.Object
com.codename1.io.FileSystemStorage

public final 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:

    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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ROOT_TYPE_MAINSTORAGE`
  Represents the type for the get root type method, this type generally represents the main phone memory
  `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.
  `static final 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
  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)`
  Returns the time that the file denoted by this abstract pathname was last modified.
  `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 Object

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

- ## Field Details

  - ### 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 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`: the root whose type we are checking

    ###### Returns

    one of the type constants above

  - ### listFiles

    public String[] listFiles(String directory) throws java.io.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:
      `java.io.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)

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

    ###### Returns

    Returns:

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

      ###### Deprecated

  - ### 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 java.io.IOException

    Opens an output stream to the given file

    ###### Parameters

    - `file`: the file

    ###### Returns

    the output stream

    Throws:
      `java.io.IOException`

  - ### openInputStream

    public InputStream openInputStream(String file) throws java.io.IOException

    Opens an input stream to the given file

    ###### Parameters

    - `file`: the file

    ###### Returns

    the input stream

    Throws:
      `java.io.IOException`

  - ### openOutputStream

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

    Opens an output stream to the given file

    ###### Parameters

    - `file`: the file

    - `offset`: position in the file

    ###### Returns

    the output stream

    Throws:
      `java.io.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 `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`: A file system path.

    ###### Returns

    The native path.