dispatchEvent

One of the most important new features in Apollo is the ability to access the local file system directly. This provides developers with the ability to read and edit text or html files, save preferences locally, store application states as external files, serialize and de-serialize data and much more. This tutorial will cover the File API features in Apollo step-by-step and will serve as a supplement to the talk I recently gave at the New York Flex Users Group.

This tutorial will be presented in multiple sections. This first will cover the File and FileStream classes and the subsequent ones will cover the Flex components used for viewing and accessing the file system and serializing and de-serializing data.

Sample code

FileDemo.mxml

Here is a bit of sample code that walks through several common tasks when working with files. I’ve marked up the code with lots of comments to highlight what’s going on in each step. To run it, use this as the ApolloApplicaiton class for an Apollo project. Note: a new folder called ‘foo’ will appear on your desktop after running it.

Disclaimer and Upcoming features

The code and examples in this tutorial deal with the files stored on your local hard drive. Although none of the code is designed to do so, it may be possible to alter or delete important files with your Apollo application. You will be using this code at your own risk.

It’s also important to remember that Apollo is currently in an Alpha version and prone to changes including additional features. Here is a list of file system functionality not included in Apollo Alpha but planned for version 1.0 (according to Adobe Labs).

• Drag and drop support
• Copy and paste support
• Native file picker dialog boxes
• File extension registration
• Launching an application to handle a file type
• Security model for accessing files

The File class

A File object is a reference to a file or directory in the local file system. Files and directories both use the same type of object which results in a surprisingly simplified way of accessing data. This is an excellent example of the composite design pattern. You can distinguish files from directories by checking the isDirectory property of a file.

The file object also contains metadata for the file it points to (inherited from the FileReference class) including:

• name
• size
• type
• creation and modification dates
• application that created the file

The File class also contains static references to commonly accessed directories in the local file system. These access points are platform independent and should point to the appropriate folder for Mac or Windows systems. (i.e. userDirectory will be c://documents and settings/username for Windows and /Users/username for Mac.) In most cases, you will want to use one of these directories when creating files. These directories include:

• appStorageDirectory - Storage directory unique for each app.
• appResourceDirectory - Application’s install directory
• currentDirectory - Directory from whence the app was launched
• desktopDirectory - The current user’s desktop directory
• documentsDirectory - The current user’s documents directory
• userDirectory - The current user’s home directory

File instances contain methods for creating, copying, and deleting files and folders. These actions that could potentially slow the system down because of large file sizes come in two flavours - synchronous and asynchronous.
Synchronous actions pause all other ActionScript from continuing while they’re processing. For very large files, the app will appear to freeze up while the processing is going on. Synchronous actions, however, are much simpler to write since they don’t require event listeners.

Asynchronous actions use the event framework to notify the application when they are finished so that other code may continue to execute while the action is taking place. Most of these methods will fire a Event.COMPLETE event or a IOErrorEvent.IO_ERROR if they are successful or if they fail respectively.
A general rule is if you’re working with files that are less than 3MB, it’s probably safe to use the synchronous methods. If there is a chance your file sizes will be larger, or if you want the added robustness, use asynchronous.
Here’s a list of methods that come in synchronous and asynchronous forms:

Synchronous	Asynchronous
copyTo()	copyToAsync()
moveTo()	moveToAsync()
deleteFile()	deleteFileAsync()
deleteDirectory()	deleteDirectoryAsync()
moveToTrash()	moveToTrashAsync()
listDirectory()	listDirectoryAsync()
open()	openAsync()

The FileStream Class

The File class provides a reference to a class but in order to work with the data inside the file, you’ll need to use a FileStream object. FileStreams allow you to open a file, specified by a File object. You can choose from four file modes for reading, writing, appending (writing to the end), or editing. To do this, you can use the open() method of the file stream.

Once a file stream is open, you will be able to call one of the many read or write commands to add data or retrieve it. In this case, we’ll use UTFBytes to write string data.

Use the close() method to close the file once you’re done writing to it.

var file:File = File.desktopDirectory.resolve("foo.txt");
var stream:FileStream = new FileStream();
stream.open(file, FileMode.WRITE);
stream.writeUTFBytes("bar");
stream.close();

OK. That’s all for now. Make sure you download the sample code if you haven’t already - the comments there explain much more about the File and FileStream classes.

Next time, serializing AS3 objects to a file.

Additional resources:

• Apollo live docs
• Apollo for Adobe Flex Developers Pocket Guide