Search Flex Components Free

Custom Search

December 29, 2007

Flex 2 and FileReference API

Flash 8 introduced new FileReference and FileReferenceList classes that allow Flash applications to natively interact with remote file upload and download. As Flex 1.5 was tied to Flash Player 7, it was possible to use these features, however, it required extra code as it was necessary to tie into a native Flash 8 application. With Flex 2 and Flash Player 9, new and improved versions of FileReference and FileReferenceList classes are available allowing native and simple code from Flex to leverage these features. This TechNote explains how to use APIs in Flex 2 applications and provides a simple file uploading example.
File upload and download are popular features for inclusion in Flash/Flex applications. With Flex 1.x, these features weren't natively available. They became possible with the release of Flash Player 8, but in Flex, you have to create a wrapper object for a movie with the FileReference class, created in the Flash 8 authoring tool so that you can access the FileReference functionalities through the wrapper class. The detailed steps to use FileReferenece in Flex 1.5 are described in the following Developer Center article, Using Flash Player 8 Features in Your Flex 1.5 Application.
With Flex 2 and Flash Player 9, the newly enhanced file uploading/downloading features are natively available in Flex 2 application. There are two main classes in the package that handle file uploading and downloading in Flex 2 -- FileReference and FileReferenceList.
A FileReference object represents a physical file and you can invoke its browse method to open the file selection dialog box and to select the target file. Next, you call upload or download methods to upload or download the file. The FileReferenceList lets you select multiple files through its browse method and holds the reference in the fileList variable, which contains an array of FileReference objects. You can then loop through the list to upload or download each file. Below is a simple code snippet to upload a single file.
var req:URLRequest = new URLRequest(endpoint);
req.method = URLRequestMethod.POST;
fileRef.upload(req, param, false);
Enhancements worth mentioning include the upload method. Besides the upload target endpoint URL, it now takes two additonal input arguments -- uploadDataFieldName and testUpload. These two features were not available in the Flash 8 FileReference class.
When uploading a file, developers often request to attach additional metadata such as date/time at upload, auther name, etc. With Flash 8 FileReference, you can't attach that metadata in the POST data, other than through the URL parameter. The uploadDataFieldName parameter now allows for uploading metadata. Below is an example of the uploadDataFieldName field (name="author=John") in the network trace result.
Content-Disposition: form-data; name="author=John"; filename="doc.pdf"
Content-Type: application/octet-stream
Notice the data field precedes the file data in the POST data instead of as the value under a standalone Part. For example, if you are using O'Reilly's file upload servlet package, the data field is available through the FilePart.getName instead of ParamPart.getStringValue.
The testUpload parameter is a Boolean argument that allows Flash Player to test the connection before actually uploading the file. If the testUpload parameter is true and the file to be uploaded is larger than 10KB, Flash Player sends a test uploadPOST operation with zero content length. If the connection is verified successfully, the player sends a secondPOST operation that contains the actual file content. This feature is only available on Windows version of the Player and for files larger than 10KB. With the Flash 8 FileReference class, a POST error message on the server side was commonly observed since the testUpload was always performed. The server script normally throws an error when getting a zero length POST operation, which is observable in log files or the standard output console. With Flash Player 9, the testUpload operation is optional, and, by default, the setting is false.
The new FileReference and FileReferenceList classes offer very powerful but extremely easy to use features for Flex 2 applications to leverage. Please refer to Flex 2 Language and ActionScript 3 API documentation for more details. A simple file uploading example is included below for demonstration purpose. It uses O'Reilly file uploading package as the server side component, which you may get from
Download the example (2K).

Related Flex Tutorials