поиск

Глава 4: API для работы с файловой системой

Намусорил: Юрий «Бармалей» Яровой
В категории: AIR, ActionScript 3

Содержание

  • Синхронные и асинхронные версии методов
  • Чтение содержимого папки
  • Доступ к файловой информации
  • Процедуры копирования и перемещения файлов и папок
  • Создание файлов и папок
  • Удаление файлов и папок
  • Чтение и запись файлов
  • Введение

    Apollo имеет файловый API ввода/вывода, который позволяет приложениям считывать и создавать файлы и папки на компьютере пользователя, и в целом обладает следующим функционалом:

    • позволяет создавать и удалять файлы и папки;
    • позволяет копировать и перемещать файлы и папки;
    • позволяет получать список содержимого папок;
    • получать доступ к системной информации о файлах и папках;
    • позволяет считывать и записывать бинарные файлы;
    • позволяет считывать и записывать текстовые файлы;
    • позволяет сериализацию и десериализацию объектов ActionScript.

    Низкоуровневая функциональность для работы с файловой системой доступна только в коде ActionScript. Flex-фреймворк для Apollo содержит компоненты для работы с файлами и папками, но они являются всего лишь графическими компонентами для навигации по файловой системе и выбора файлов и папок. Эти компоненты не предоставляют прямой доступ к другим основным файловым операциям ввода/вывода.

    В дополнение к информации, содержащейся в этой главе, смотрите примеры из раздела «Работа с файловой системой» в пятой главе книги. В этих примерах иллюстрируются некоторые концепции, описанные здесь, и в них приводятся примеры работающего MXML-кода, который вы можете протестировать, используя Flex Builder или Apollo SDK.

    Модель безопасности

    Apollo, в конечном счете, будет предусматривать комплексную модель безопасности, которая будет контролировать доступ к локальным ресурсам, таким как файловая система. Однако эта модель безопасности не была включена в альфа-версию Apollo.

    Необходимо помнить о том, что Apollo-приложение устанавливается на компьютер пользователя и только после этого запускается. В следствие с этим, некоторые правила, которые используются для загрузки и запуска других приложений из интернета, также применимы для загрузки и запуска Apollo приложений. Пользователь должен загружать и устанавливать приложения только из тех источников, которым доверяет.

    Доступ к файлам и папкам

    Apollo приложения могут работать на различных платформах, например на Windows и Mac OS. Файловый API использует кроссплатформенный синтаксис кода, так что вам не придется писать код, зависящий от конкретной операционной системы.

    Вот, к примеру, различия в путях к пользовательским файлам в системах Mac OS и Windows:

    • типичный путь к файлу на Mac OS: /Users/joe/Documents/test.txt;
    • типичный путь к файлу на Windows: C:\Documents and Settings\joe\My Documents\test.txt.

    Однако в Apollo вы можете воспользоваться компонентами, классами, методами и свойствами, для простого доступа к этим файлам на различных операционных системах.

    В ActionScript объект File является указателем на какой-либо файл или папку. Класс File содержит статичное свойство documentsDirectory. В нем хранится объект типа File, который в свою очередь является указателем на папку с документами пользователя. Т. е. на папку «My Documents» в Windows, и на папку «Documents» в пользовательской директории на Mac OS, как показано в следующем примере:

    Actionscript:
    1. trace(File.documentsDirectory.nativePath)
    2. // В Windows: C:\Documents and Settings\joe\MyDocuments
    3. // В Mac OS: /Users/joe/Documents

    В том случае, если объект File является указателем на директорию, то вы можете воспользоваться методом resolve(), для смены этого указателя на файл или папку, находящиеся в этой директории, даже если ни файл, ни папка еще не существуют. Например, следующий код создает подпапку Apollo Test в директории документов пользователя:

    Actionscript:
    1. var newDir:File = File.documentsDirectory;
    2. newDir = newDir.resolve("ApolloTest");
    3. newDir.createDirectory( );

    Объект File может указывать на любой файл или директорию. Кроме того, объект File может указывать даже на несуществующий файл или папку, как было показано в предыдущем примере. Это позволяет экземпляру File ссылаться на директорию, которую вы еще только желаете создать.

    Свойства класса File для доступа к основным директориям системы

    Класс File содержит следующие статические свойства, которые указывают на часто используемые папки на компьютерах пользователей:

    Свойство Описание
    File.appStorageDirectory Каждое установленное Apollo приложение получает в свое распоряжение директорию для хранения собственных ресурсов. Это отличное место для хранения файлов, которые могут требоваться для работы приложения, но которые лучше не показывать пользователю. Здесь можно хранить лог-файлы, файлы кэша и файлы с настройками приложения.
    File.appResourceDirectory Папка установки приложения.
    File.currentDirectory Это директория, в которой был запущен файл. Вы можете использовать это свойство для определения пути к файлу и получения любого параметра командной строки, которые были переданы приложению.
    File.desktopDirectory Папка рабочего стола пользователя.
    File.documentsDirectory Папка документов пользователя. «My Documents» в Windows, и подпапка «Document» в папке пользователя на Mac OS.
    File.userDirectory Домашняя директория пользователя. Для примера, в Mac OS это папка Users/username, а в Windows обычно это папка c:\\Document and Settings\username.

    Свойства url и nativePath объекта File

    Свойство url объекта File возвращает расположение файла или папки в виде кроссплатформенной URL строки, как показано в следующем примере:

    Actionscript:
    1. var directory:File = File.userDirectory;
    2. trace(directory.url)
    3. // в Windows: file:///C:/Documents%20and%20Settings
    4. // в Mac OS: file:///Users

    В то же время, свойство nativePath возвращает строку в адресной нотации текущей операционной системы. Например, вы можете использовать следующий код для получения доступа к определенному файлу в Windows:

    Actionscript:
    1. var file:File = new File( );
    2. file.nativePath = "c:/ApolloTest/surprise.txt";

    Но вместо этого гораздо надежнее воспользоваться одним из свойств, перечисленных в вышележащей таблице (например, свойством appStorageDirectory, которое указывает на папку установки приложения независимо от операционной системы) и методом resolve(), чтобы создать относительный путь к нужному нам файлу:

    Actionscript:
    1. var logFile:File = File.appStorageDirectory;
    2. logFile = logFile.resolve("log.txt");

    Не забывайте, то в директории File.appStorageDirectory можно хранить файлы, которые потребуются приложению в будущем, но для которых нежелательно, чтобы о них знал пользователь.

    Структуры URI

    Структура URI определяет начало URL, так как строка «file» в следующем примере:

    Actionscript:
    1. file:///c:/ApolloTest/test.txt

    app-storage

    Обозначает директорию для хранения ресурсов приложения, как показано в следующем примере:

    Actionscript:
    1. var logFile:File = File.appStorageDirectory;
    2. logFile = logFile.resolve("log.txt");
    3. trace(logFile.url); // app-storage:/log.txt

    app-resource

    Обозначает папку установки приложения, как показано ниже:

    Actionscript:
    1. var installDir:File = new File( );
    2. installDir.url = "app-resource:/";
    3. installDir = installDir.resolve("HelloWorld-app.xml");
    4. trace(installDir.url); // app-resource:/HelloWorld-app.xml

    file

    Свойство url других объектов File возвращает URL с путем к файлу в стандартной file схеме URI:

    Actionscript:
    1. var file:File = File.documentsDirectory;
    2. file = file.resolve("ApolloTest/test.txt");
    3. trace(file.url);
    4. // On Windows:
    5. // file:///C:/Documents%20and %20Settings/ ... /test.txt
    6. // On Mac OS:
    7. // file:///Users/userName/Documents/ ... /test.txt

    Синхронные и асинхронные версии методов

    Многие методы классов File и FileStream (такие как File.copyFile() и File.copyFileAsync()) имеют как синхронные, так и асинхронные версии.

    Синхронные методы не передают управление другим ActionScript инструкциям до завершения файловой операции. Асинхронные методы работают в фоновом режиме, позволяя в это время исполняться другим ActionScript процессам. Когда асинхронная файловая операция завершается, производится рассылка события всем слушателям о том, что операция выполнена.

    Следующий пример иллюстрирует операцию копирования файла с использованием синхронного метода copyTo():

    Actionscript:
    1. var file1:File = File.documentsDirectory.resolve("ApolloTest/test.txt");
    2. var file2:File = File.documentsDirectory.resolve("ApolloTest/copy of test.txt");
    3. file1.copyTo(file2);
    4. trace("Ничего не выводится в панель Output пока файл не скопируется.");

    В следующем примере показано копирование файла с использованием асинхронного метода copyToAsync():

    Actionscript:
    1. var file1:File = File.documentsDirectory.resolve("ApolloTest/test.txt");
    2. var file2:File = File.documentsDirectory.resolve("ApolloTest/copy of test.txt");
    3. file1.copyToAsync(file2);
    4. file1.addEventListener(Event.COMPLETE, completeHandler);
    5. trace("Эта строка кода выполняется до завершения копирования.");
    6. trace("Так же как и эта.");
    7. private function completeHandler(event:Event):void {
    8.     trace("Выполнено.");
    9. }

    В следующей таблице перечислены асинхронные методы класса File (для каждого из которых есть свой синхронный аналог) и события, которые рассылаются после выполнения метода:

    Асинхронный файловый метод События
    copyToAsync() complete, ioError
    deleteDirectoryAsync() complete, ioError
    deleteFileAsync() complete, ioError
    listDirectoryAsync() directoryListing, ioError
    moveToAsync() complete, ioError
    moveToTrashAsync() complete, ioError

    Для того чтобы открыть файл используйте метод open() или openAsync() объекта FileStream. В первом случае операция открытия файла является синхронной, во втором — асинхронной. Чтобы узнать больше про эти методы, смотрите раздел «Методы open() и openAsync()» ниже в этой главе.

    Используйте асинхронные методы там, где вы хотите быть уверенными, что основной ActionScript процесс (такой, например, как обновление прогресса выполнения операции) не будет остановлен во время выполнения файловой операции. Т.е. вы можете использовать синхронный метод open() объекта FileStream, если собираетесь открыть файл размером менее 1 Мб, однако используйте метод openAsync() если размер открываемого файла большой или заранее не известен.

    За дополнительной информацией об асинхронных методах обратитесь к главе «Handling Events» книги «Programming ActionScript 3.0».

    Чтение содержимого папки

    Метод File.listDirectory() возвращает массив, состоящий из объектов типа File, представляющих собой файлы и папки, содержащиеся в директории, для которой был вызван этот метод. Для примера, следующий код выводит список содержимого папки рабочего стола:

    Actionscript:
    1. var directory:File = File.desktopDirectory;
    2. var contents:Array = directory.listDirectory( );
    3. for (var i:uint = 0; i <contents.length; i++) {
    4.     if (contents[i].isDirectory) {
    5.         trace(contents[i].name);
    6.     } else {
    7.         trace(contents[i].name,
    8.         contents[i].size,
    9.         "bytes");
    10.     }
    11. }

    Метод File.listDirectory() возвращает массив состоящий из файлов и папок, только непосредственно находящихся в текущей директории. Т.е. он не возвращает содержимое подпапок. Но вы, конечно же, можете написать код, обходящий вложенные папки, для того, чтобы получить список их содержимого, воспользовавшись методом File.listDirectoryAsync(), чтобы позволить выполняться другому ActionScript коду, до того момента, пока операция обхода вложенных папок не будет выполнена.

    За дополнительной информацией об асинхронных методах обратитесь к главе «Handling Events» книги «Programming ActionScript 3.0».

    Доступ к файловой информации

    В классе File содержится несколько свойств, с помощью которых можно получить информацию о файле или папке.

    Свойство Описание
    exists Состояние, когда файл или папка существует. Свойство необходимо проверять, перед тем как, например, попытаться прочитать, записать, копировать, или переместить файл.
    isDirectory Свойство, показывающее, что объект File является указателем на папку (true) или файл (false). Вам нужно будет проверять это свойство до того, как вы будете проводить над объектом операции, присущие папкам (такие, как метод listDirectory()) или файлам (чтение, запись).
    isHidden Показывает, является ли файл или папка скрытым.
    nativePath Путь до папки или файла в виде строки, в нотации текущей операционной системы.
    parent Указатель на вышележащую директорию в виде экземпляра класса File.
    url Путь до файла или папки в независимой от текущей операционной системы URL-нотации.

    Кроме того, класс File унаследовал от класса FileReference несколько полезных свойств:

    Свойство Описание
    creationDate Дата создания файла или папки.
    modificationDate Дата последней модификации файла.
    name Название файла или папки.
    size Размер файла в байтах.

    Copying and Moving

    Процедуры копирования и перемещения файлов и папок

    Методы File.copyTo() и File.moveTo(), соответственно, копируют и перемещают файл или папку в указанное новое местоположение. Например, следующий код копирует файл test.txt, находящийся в папке Apollo Test, которая находится в папке документов пользователя, в папку User Data, находящуюся в папке хранения ресурсов приложения:

    Actionscript:
    1. var file1:File = File.documentsDirectory.resolve("Apollo Test/test.txt");
    2. var destination:File = File.appStorageDirectory.resolve("User Data");
    3. destination.createDirectory();
    4. var file2:File = destination.resolve("test.txt");
    5. file1.copyTo(file2);

    Используйте асинхронные версии File.copyToAsync() и File.moveToAsync() этих методов, если операция копирования или перемещения может занять много времени.

    Каждый из этих методов содержит параметр clobber, установка значения true которого включает режим перезаписи исходных файлов. По умолчанию значением параметра является false.

    Создание файлов и папок

    Статичные методы File.createTempFile() и File.createTempDirectory() класса File позволяют вам создавать временные файлы и папки. Apollo гарантирует, что файл или папка, созданные при помощи этих методов, будут новыми, и будут иметь уникальные названия. Для примера, следующий код создает временный файл:

    Actionscript:
    1. var bufferStorage:File = File.createTempFile();

    Временные файлы и папки не удаляются автоматически при закрытии Apollo приложения. Необходимо «вручную» удалять их перед закрытием. Смотрите раздел «Удаление файлов и папок» для получения дополнительных сведений об операциях удаления.

    Метод File.createDirectory() позволяет вам создавать новые папки в локациях, определяемых объектом File:

    Actionscript:
    1. var directory = File.documentsDirectory;
    2. directory = directory.resolve("ApolloTest");

    Когда вы открываете объект FileStream для операций записи, то папки, содержащиеся в пути к файлу, создаются автоматически, если это необходимо. Для получения дополнительной информации об объекте FileStream обратитесь к разделу «Чтение и запись файлов» ниже в этой главе.

    Удаление файлов и папок

    Метод File.deleteFile() удаляет файл. Метод File.deleteDirectory() удаляет папку. Метод File.moveToTrash() позволяет вам переместить файл или директорию в системную корзину.

    Каждый из этих методов имеет асинхронный аналог.

    Чтение и запись файлов

    Класс FileStream предоставляет методы, позволяющие приложению читать и записывать данные в файл.

    Ниже представлен приблизительный процесс считывания и записи данных в файл:

    1. Создание объекта класса File, являющегося указателем на файл, данные которого необходимо прочесть или записать. За подробностями обратитесь к разделу «Доступ к файлам и папкам» выше в этой главе.
    2. Создать экземпляр объекта FileStream, к примеру, следующим образом:

      Actionscript:
      1. var stream:FileStream = new FileStream( );

    3. Вызвать метод FileStream.open() или FileStream.openAsync(), передав ему в качестве параметра объект класса File, указывающий на необходимый файл, а так же определенный режим открытия файла в виде параметра fileMode. Пример:

      Actionscript:
      1. stream.open(file, FileMode.READ);

      Для получения дополнительной информации смотрите раздел «Режимы открытия файлов» ниже в этой главе.

    4. Если был вызван асинхронный метод FileStream.openAsync(), то необходимо также назначить метод слушатель события открытия файла, как это делается, смотрите в разделе «Методы open() and openAsync()» чуть ниже.
    5. Произвести операции по чтению и записи данных в файл. За дополнительной информацией обратитесь к разделу «Методы записи и чтения» ниже в этой главе.
    6. Закрыть файл, используя метод FileStream.close(), например:

      Actionscript:
      1. stream.close();

    Разберем более детально шаги 3, 4 и 5. Для начала, рассмотрим синхронную процедуру чтения текста в кодировке UTF-8 из файла:

    Actionscript:
    1. var file:File = File.appStorageDirectory;
    2. file = file.resolve("settings.xml");
    3. var stream:FileStream = new FileStream();
    4. stream.open(file, FileMode.READ);
    5. var data:String = stream.readUTFBytes(stream.bytesAvailable);
    6. stream.close();

    А это та же самая операция, но в асинхронном варианте:

    Actionscript:
    1. var file:File = File.appStorageDirectory;
    2. file = file.resolve("settings.xml");
    3. var stream:FileStream = new FileStream();
    4. stream.openAsync(file, FileMode.READ);
    5. stream.addEventListener(Event.COMPLETE, readData);
    6. var data:String;
    7. private function readData(event:Event):void {
    8.     data = stream.readUTFBytes(stream.bytesAvailable);
    9.     stream.close();
    10. }

    Методы open() и openAsync()

    Вашему приложению необходимо открыть файл до того как будет произведено чтение или запись данных из него.

    Когда вы открываете файл асинхронным методом FileStream.openAsync(), то вам нужно зарегистрировать слушателей событий для отслеживания прогресса операции открытия.

    Вызов метода FileStream.open() является синхронной операцией. Если ваше приложение открывает файл, используя синхронный метод, то до завершения файловой операции не будет выполняться никакой другой код в приложении. Так, в следующем примере, сначала будут полностью завершены методы stream.open(), stream.writeUTFBytes(), stream.close(), и только после этого будет возможно выполнение следующего кода:

    Actionscript:
    1. var newFile:File = File.documentsDirectory;
    2. file = file.resolve("ApolloTest/test.txt");
    3. var stream:FileStream = new FileStream()
    4. stream.open(file, FileMode.WRITE);
    5. stream.writeUTFBytes("This is some sample text.");
    6. stream.close();

    Преимуществом открытия файла с использованием синхронной операции является то, что вам придется писать меньшее количество кода для осуществления этой задачи. Минусом является то, что выполнение другого ActionScript кода будет приостановлено на время выполнения операции. Как результат, если вы работаете с файлами большими по объему, либо файлами, доступ к которым осуществляется через медленное сетевое соединение, то нужно будет подумать о целесообразности применения асинхронного метода FileStream.openAsync().

    Когда вы используете метод FileStream.openAsync(), то все следующие процессы должны быть обработаны асинхронно с помощью слушателей событий:

    • Закрытие файла. Объект FileStream рассылает событие close, когда файл закрыт.
    • Чтение данных в буфер. Объект FileStream рассылает событие progress во время считывания новой порции данных из файла и событие complete, когда все данные прочитаны. Если данные из файла были уже прочитаны однажды, то вызов метода чтения повторно (такого как, readBytes()) выполнит чтение как синхронный процесс.
    • Ошибки ввода/вывода. Объект FileStream рассылает событие ioError при обнаружении ошибки. Для этого возможно несколько причин, например, была произведена попытка записи в файл, когда тот открывался только для чтения. Однако, некоторые ошибки, такие, например, как доступ к чтению данных из файла в то время, когда файл еще не был открыт, вызывают выброс исключений (более значимых, чем рассылка события ioError), потому что среда исполнения Apollo смогла обнаружить сбойную ситуацию незамедлительно.

    Перед вызовом метода FileStream.openAsync() в вашем приложении необходимо определить функции слушатели события, которые будут вызваны по завершению асинхронной операции открытия файла.

    Следующий пример иллюстрирует асинхронное открытие файла в режиме чтения. После того как файл будет открыт, будет разослано событие завершения операции (либо, если будет обнаружена ошибка, будет разослано событие ошибочного завершения операции ioError, как только ошибка будет обнаружена). В теле пользовательского обработчика события completeHandler() происходит вызов метода FileStream.readBytes(), который в асинхронном режиме считывает данные из файла в массив байтов. Когда все байты данных файла будут прочитаны, будет разослано событие complete:

    Actionscript:
    1. var file:File = File.documentsDirectory.resolve("ApolloTest/test.txt");
    2. var stream:FileStream = new FileStream();
    3. stream.addEventListener(ProgressEvent.PROGRESS, progressHandler);
    4. stream.addEventListener(Event.COMPLETE, completeHandler);
    5. stream.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
    6. stream.addEventListener(Event.CLOSE, closeHandler);
    7. stream.openAsync(file, FileMode.READ);
    8. var data:ByteArray = new ByteArray();
    9. private function progressHandler(event:ProgressEvent):void {
    10.     trace(stream.bytesAvailable, "байты считаны.");
    11. }
    12. private function completeHandler(event: Event):void {
    13.     data = stream.readBytes(stream.bytesAvailable);
    14.     stream.close();
    15. }
    16. private function ioErrorHandler(event:IOErrorEvent):void {
    17.     trace("Обнаружена ошибка операции ввода/вывода.");
    18. }
    19. private function closeHandler(event: Event):void {
    20.     trace("Файл закрыт.");
    21. }

    Режимы открытия файлов

    Оба метода FileStream.open() и FileStream.openAsync() принимают два параметра: параметр file, являющийся указателем на файл, который необходимо открыть, и параметр fileMode, являющийся строкой, определяющей, с какими правами будет произведено открытие файла. Все возможные значения параметра fileMode определены в качестве констант класса FileMode.

    Например, следующий код синхронно открывает файл для записи в него данных, но не для чтения:

    Actionscript:
    1. stream.open(file, FileMode.WRITE);

    В таблице перечислены константы класса FileMode и их описание:

    Константа Определение
    FileMode.APPEND Файл открывается только для записи, причем вся записываемая информация добавляется в конец файла. Перед открытием проверяется существование файла, и если файл еще не существует, то он создается автоматически.
    FileMode.READ Файл открывается только для чтения. Файл должен существовать (при его отсутствии он не создается).
    FileMode.UPDATE Файл открывается в режиме чтения/записи. И запись данных возможна в любую позицию файла. Если файл не существует, то он создается.
    FileMode.WRITE Файл открывается только в режиме записи. Если файл не существует, то он создается. При открытии файл будет полностью перезаписан.

    Методы чтения и записи

    Класс FileStream содержит некоторое число методов чтения и записи, которые приводят данные к определенному формату перед их записью или чтением. Например, вы можете использовать методы readUTFBytes() и writeUTFBytes() для того, чтобы прочитать или записать массив байтов, или же методы readByte() и writeByte() чтобы прочитать или записать одиночный байт данных. Всего в этом классе содержится 26 методов чтения и записи данных. За детальными описаниями этих методов обратитесь к документации по классу FileStream в Справочнике по языку ActionScript, который распространяется вместе с Apollo.

    Хотя чтение и запись текстовых данных может показаться вам тривиальной задачей, вы всегда должны учитывать кодировку текстового файла. Методы readUTFBytes() and writeUTFBytes() предоставляют возможность считывать и записывать текст в кодировке UTF-8. Методы readMultiByte() и writeMultiByte() позволяют вам определять распознавать различные кодировки символов файла. Однако все возможные ситуации предугадать нельзя. Например, файл в кодировке UTF-8 может начинаться с маркирующего байта (BOM), указывающего на кодировку UTF-8, но содержать при этом кусок данных в другой кодировке.

    За дополнительной информацией обратитесь к разделу «Data formats, and choosing the read and write methods to use» в Apollo Developer’s Guide.

    Дополнительная информация

    За примерами чтения и записи данных в файл обратитесь к следующим разделам главы 5:

    • Запись текстового файла из строки (объекта String);
    • Чтение текстового файла в строку (в объект String);
    • Конвертация изображений (объектов BitmapData) в форматы PNG или JPEG, а так же их запись в файловой системе;
    • Сериализация и десериализация объектов ActionScript для их сохранения в виде файлов.
    

    Написать комментарий:

     

    Bы можете использовать следующие теги для форматирования: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

    

    User's collector

    Внимание!
    Эта опция станет доступной только после того как вы авторизуетесь.

    
     запомнить меня 
    Я новый пользователь

    На правах рекламы