Working with the file system

Back to: Apollo Documentation home page

You use the classes provided by the Apollo file API to access the file system of the host computer. To begin, refer to Apollo file basics and then to the following topics, which explain the common file system tasks:

• Working with File objects
• Getting file system information
• Working with directories
• Creating directories
• Creating a temporary directory
• Enumerating directories
• Copying and moving directories
• Deleting directory contents
• Working with files
• Getting file information
• Copying and moving files
• Deleting a file
• Moving a file to the trash
• Creating a temporary file
• Reading and writing files

If you're developing Apollo applications using Flex, you can refer to the following quick starts:

• Building a text file editor
• Building a text file editor in Flex
• Reading and writing an XML preferences file (Flex)
• Building a directory search application (Flex)

The Apollo file API contains the following classes:

• flash.filesystem package:
• File
• FileMode
• FileStream

Contents
Apollo file basics Synchronous and asynchronous methods Working with File objects Pointing a File object to a directory Pointing a File object to a file Pointing to an explicit file path Enumerating files in a directory Modifying File paths Supported URL schemes Finding the relative path between two files Using the canonicalize() method Getting file system information

---

Apollo file basics

Adobe Apollo provides classes that you can use to access, create, and manage both files and folders. These classes, contained in flash.filesystem, are used for the following:

File

A File object represents a path to a file or directory. You use a file object to create a pointer to a file or folder, initiating interaction with the file or folder.

FileMode

The FileMode class defines string constants used in the fileMode parameter of the open() and openAsync() methods of the FileStream class. The fileMode parameter of these methods determines the capabilities available to the FileStream object once the file is opened, which include writing, reading, appending, and updating.

FileStream

A FileStream object is used to open files for reading and writing. Once you’ve created a File object that points to a new or existing file, you pass that pointer to the FileStream object so that you can open and then manipulate data within the file.

Synchronous and asynchronous methods

Some methods in the File class have both synchronous and asynchronous versions:

• File.copyTo() and File.copyToAsync()
• File.deleteDirectory() and File.deleteDirectoryAsync()
• File.deleteFile() and File.deleteFileAsync()
• File.listDirectory() and File.listDirectoryAsync()
• File.moveTo() and File.moveToAsync()
• File.moveToTrash() and File.moveToTrashAsync()

Also, FileStream operations work synchronously depending on how the FileStream object opens the file: by calling the open() or by calling openAsync() method.

The asynchronous versions let you initiate processes that run in the background and dispatch events when complete (or when error events occur). Other code can execute while these asynchronous background processes are taking place. With asynchronous versions of the operations, you need to set up event listener functions, using the addEventListener() method of the object that calls the function.

The synchronous versions let you write simpler code that does not rely on setting up event listeners. However, since other code cannot execute while a synchronous method is executing, important processes, such as display object rendering and animation, may be paused.

Working with File objects

The File object is a pointer to a file or directory in the file system.

The File class extends the FileReference class. The FileReference class, which is available in Flash Player as well as Apollo, represents a pointer to a file, but the File class adds properties and methods that should not be exposed in Flash Player (in a SWF running in a browser), due to security considerations.

You can use the File class for each of the following:

• Getting the path to special directories, including the user directory, the user's documents directory, the directory from which the application was launched, and the application directory
• Coping files and directories
• Moving files and directories
• Deleting files and directories (or moving them to the trash)
• Listing files and directories contained in a directory
• Creating temporary files and folders

Once a File object points to a file path, you can use it to read and write files, using the FileStream class.

A File object can point to the path of a file or directory that does not yet exist. You can use such a File object in creating a new file or directory.

Pointing a File object to a directory

There are a number of ways to set a File object to point to a directory.

You can point a File object to the user's home directory. On Windows, the home directory is the parent of the "My Documents" directory (for example, "C:\Documents and Settings\userName\My Documents"). On Mac OS, it is the Users/userName directory. The following code sets a File object to point to an Apollo Test subdirectory of the home directory:

ActionScript example:

  var file:File = File.userDirectory.resolve("Apollo Test");

JavaScript example:

  var file = runtime.flash.filesystem.File.userDirectory.resolve("Apollo Test");

You can point a File object to the user's documents directory. On Windows, this is typically the "My Documents" directory (for example, "C:\Documents and Settings\userName\My Documents"). On Mac OS, it is the Users/userName/Documents directory. The following code sets a File object to point to an Apollo Test subdirectory of the documents directory:

ActionScript example:

  var file:File = File.documentsDirectory.resolve("Apollo Test");

JavaScript example:

  var file = runtime.flash.filesystem.File.documentsDirectory.resolve("Apollo Test");

You can point a File object to the desktop. The following code sets a File object to point to an Apollo Test subdirectory of the desktop:

ActionScript example:

  var file:File = File.desktopDirectory.resolve("Apollo Test");
  

JavaScript example:

  var file = runtime.flash.filesystem.File.desktopDirectory.resolve("Apollo Test");

You can point a File object to the application store directory. For every Apollo application, there is a unique associated path that defines the application store directory. You may want to use this directory to store application-specific data (such as user data or preferences files).

ActionScript example:

  var file:File = File.appStoreDirectory;

JavaScript example:

  var file = runtime.flash.filesystem.File.appStoreDirectory;

You can also set a File object to point to directory from which the the application started, known as the "current directory," as illustrated in the following code:

ActionScript example:

  var file:File = File.currentDirectory;

JavaScript example:

  var file = runtime.flash.filesystem.File.currentDirectory;

The File.listRootDirectories() lists all root volumes, such as C: and mounted volumes, on a Windows computer. On Mac, this method always returns the unique root directory for the machine (the "/" directory).

You can point the File object to an explicit directory by setting the nativePath property of the File object, as in the following example (on Windows):

ActionScript example:

  var file:File = new File();
  file.nativePath = "C:\\Apollo Test\\";

JavaScript example:

  var file = new runtime.flash.filesystem.File();
  file.nativePath = "C:\\Apollo Test\\";

You can use the resolve() method to obtain a path relative to another given path. For example, the following code sets a File object to point to an "Apollo Test" subdirectory of the user's home directory:

ActionScript example:

  var file:File = File.userDirectory;
  file = file.resolve("Apollo Test");

JavaScript example:

  var file = runtime.flash.filesystem.File.userDirectory;
  file = file.resolve("Apollo Test");

You can also use the url property of a File object to point it to a directory based on a URL string, as in the following:

ActionScript example:

  var urlStr:String = "file:/C:/Apollo Test/";
  var file:File = new File()
  fil.url = urlStr;

JavaScript example:

  var urlStr = "file:/C:/Apollo Test/";
  var file = new runtime.flash.filesystem.File()
  fil.url = urlStr;

You can also use the nativePath property of a File object to set an explicit path. For example, the following code, when run on a Windows computer, sets a File object to the Apollo Test subdirectory of the C: drive:

ActionScript example:

  var file:File = new File();
  file.nativePath = "C:\\Apollo Test";

JavaScript example:

  var file = new runtime.flash.FileSystem.File();
  file.nativePath = "C:\\Apollo Test";

For more information, see Modifying File paths.

Pointing a File object to a file

There are a number of ways to set the file to which a File object points.

Pointing to an explicit file path

You can use the resolve() method to obtain a path relative to another given path. For example, the following code sets a File object to point to a log.txt file within the application store directory:

ActionScript example:

  var file:File = File.appStoreDirectory;
  file = file.resolve("log.txt");

JavaScript example:

  var file:File = runtime.flash.filesystem.File.appStoreDirectory;
  file = file.resolve("log.txt");

You can use the url property of a File object to point it to a file or directory based on a URL string, as in the following:

ActionScript example:

  var urlStr:String = "file:/C:/Apollo Test/test.txt";
  var file:File = new File()
  file.url = urlStr;

JavaScript example:

  var urlStr = "file:/C:/Apollo Test/test.txt";
  var file = new runtime.flash.filesystem.File()
  file.url = urlStr;

Note that url property always returns the URI-encoded verson of the URL (for example, blank spaces are replaced with "%20):

ActionScript example:

  file.url = "file:///c:/Apollo Test";
  trace(file.url); // file:///c:/Apollo%20Test

JavaScript example:

  file.url = "file:///c:/Apollo Test";
  alert(file.url); // file:///c:/Apollo%20Test

You can also use the nativePath property of a File object to set an explicit path. For example, the following code, when run on a Windows computer, sets a File object to the test.txt file in the Apollo Test subdirectory of the C: drive:

ActionScript example:

  var file:File = new File();
  file.nativePath = "C://Apollo Test/test.txt";

JavaScript example:

  var file = new runtime.flash.filesystem.File();
  file.nativePath = "C://Apollo Test/test.txt";

On Windows you can use the forward slash (/) or backslash (\) character as the path delimiter for the nativePath property. On Mac OS, use the forward slash (/) character as the path delimiter for the nativePath :

ActionScript example:

  var file:File = new File();
  file.nativePath = "Users/dijkstra/Apollo Test/test.txt";
  

JavaScript example:

  var file = new runtime.flash.filesystem.File();
  file.nativePath = "Users/dijkstra/Apollo Test/test.txt";
  

For more information, see Modifying File paths.

Enumerating files in a directory

You can use the listDirectory() method of a File object to get an array of File objects pointing to files and subdirectories at the root level of a directory. For more information, see Enumerating directories.

Modifying File paths

You can also modify the path of an existing File object by calling the resolve() method or by modifying the nativePath or url property of the object, as in the following examples (on Windows):

ActionScript examples:

  var file1:File = File.documentsDirectory;
  file1 = file1.resolve("Apollo Test");
  trace(file1.nativePath); // C:\Documents and Settings\userName\My Documents\Apollo Test

  var file2:File = File.documentsDirectory;
  file2 = file2.resolve("..");
  trace(file2.nativePath); // C:\Documents and Settings\userName

  var file3:File = File.documentsDirectory;
  file3.nativePath += "/subdirectory";
  trace(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectory

  var file4:File = new File();
  file.url = "file:///c:/Apollo Test/test.txt"
  trace(file3.nativePath); // C:\ApolloTest\test.txt

JavaScript examples:

  var file1 = runtime.flash.filesystem.File.documentsDirectory;
  file1 = file1.resolve("Apollo Test");
  alert(file1.nativePath); // C:\Documents and Settings\userName\My Documents\Apollo Test

  var file2 = runtime.flash.filesystem.File.documentsDirectory;
  file2 = file2.resolve("..");
  alert(file2.nativePath); // C:\Documents and Settings\userName

  var file3 = runtime.flash.filesystem.File.documentsDirectory;
  file3.nativePath += "/subdirectory";
  alert(file3.nativePath); // C:\Documents and Settings\userName\My Documents\subdirectory

  var file4 = new runtime.flash.filesystem.File();
  file.url = "file:///c:/Apollo Test/test.txt"
  alert(file3.nativePath); // C:\ApolloTest\test.txt

When using the nativePath property, you use either the forward slash (/) or backslash (\) character as the directory separator character on Windows; use the forward slash (/) character on Mac OS. On Windows, remember to type the backslash character twice in a string literal.

Supported URL schemes

You can use any of the following URL schemes in defining the url property of a File object:

• file: — Use this to specify a path relative to the root of the file system. For example:

• file:///c:/Apollo Test/test.txt

• app-resource: — Use this to specify a path relative to the root directory of the installed application (the directory that contains the application.xml file for the installed application). For example, the following path points to a test.log file in a logs subdirectory of the directory of the installed application:

• app-resource:/logs/test.log

• app-storage:/ — Use this to specify a path relative to the application store directory. For each installed application, Apollo defines a unique application store directory, which is a useful place to store data specific to that application. For example, the following path points to a prefs.xml file in a settings subdirectory of the application store directory:

• app-storage:/settings/prefs.xml

Finding the relative path between two files

You can use the relativize method to find the relative path between two files:

ActionScript example:

  var file1:File = File.documentsDirectory.resolve("Apollo Test");
  var file2:File = File.documentsDirectory.resolve("Apollo Test/bob/test.txt");
  
  trace(file1.relativize(file2)); //bob/test.txt

JavaScript example:

  var file1 = runtime.flash.filesystem.File.documentsDirectory.resolve("Apollo Test");
  var file2 = runtime.flash.filesystem.File.documentsDirectory.resolve("Apollo Test/bob/test.txt");
  
  trace(file1.relativize(file2)); //bob/test.txt

The second parameter of the relativize() method, the useDotDot parameter, allows for .. syntax to to be returned in results, to indicate parent directories:

ActionScript example:

  var file1:File = File.documentsDirectory.resolve("Apollo Test");
  var file2:File = File.documentsDirectory.resolve("Apollo Test/bob/test.txt");
  var file3:File = File.documentsDirectory.resolve("Apollo Test/susan/test.txt");
  
  trace(file2.relativize(file1, true)); // ../..
  trace(file3.relativize(file2, true)); // ../../bob/test.txt

JavaScript example:

  var file1 = runtime.flash.filesystem.File.documentsDirectory.resolve("Apollo Test");
  var file2 = runtime.flash.filesystem.File.documentsDirectory.resolve("Apollo Test/bob/test.txt");
  var file3 = runtime.flash.filesystem.File.documentsDirectory.resolve("Apollo Test/susan/test.txt");
  
  trace(file2.relativize(file1, true)); // ../..
  trace(file3.relativize(file2, true)); // ../../bob/test.txt

Using the canonicalize() method

File and path names are usually not case sensitive. In the following, two ActionScript File objects point to the same file:

  File.documentsDirectory.resolve("test.txt");
  File.documentsDirectory.resolve("TeSt.TxT");

However, documents and directory names do include capitalization. For example, the following assumes that there is a folder named "Apollo Test" in the documents directory, as in the following examples:

ActionScript example:

  var file:File = File.documentsDirectory.resolve("apollo test");
  trace(file.nativePath); // ... apollo test
  file.canonicalize();
  trace(file.nativePath); // ... Apollo Test

JavaScript example:

  var file = runtime.flash.filesystem.File.documentsDirectory.resolve("apollo test");
  trace(file.nativePath); // ... apollo test
  file.canonicalize();
  alert(file.nativePath); // ... Apollo Test

The canonicalize method converts the nativePath object to use the correct capitalization for the file or directory name.

You can also use the canonicalize() method to convert short file names ("8.3" names) to long file names on Windows, as in the following examples:

ActionScript example:

  var path:File = new File();
  path.nativePath = "C:\\Apollo~1";
  path.canonicalize();
  trace(path.nativePath); // C:\Apollo Test

JavaScript example:

  var path = new runtime.flash.filesystem.File();
  path.nativePath = "C:\\Apollo~1";
  path.canonicalize();
  alert(path.nativePath); // C:\Apollo Test

Getting file system information

The File class includes the following static constants that provide some useful information about the file system:

Constant	Description
File.encoding	The default encoding used for files by the host operating system. This pertains to the character set used by the operating system, corresponding to its language.
File.lineEnding	The line-ending character sequence used by the host operating system. On Mac OS, this is the line-feed character. On Windows, this is the carriage return character followed by the line-feed character.
File.separator	The host operating system's path component separator character. On Mac OS, this is the colon (":") character. On Windows, it is the backslash ("\") character. (Note: In future releases of Apollo, the File.separator property will be set to the forward slash ("/") character.)

The flash.system.Capabilities class also includes useful system information that may be useful when working with files:

Property	Description
Capabilities.hasIME	Specifies whether the player is running on a system that does (true) or does not (false) have an input method editor (IME) installed.
Capabilities.language	Specifies the language code of the system on which the player is running.
Capabilities.os	Specifies the current operating system.

---

Back to: Apollo Documentation home page