Ejemplo: carga y descarga de archivos -- Flash CS3

El ejemplo FileIO muestra las técnicas para cargar y descargar archivos en Flash Player. Estas técnicas son:

Para obtener los archivos de aplicación de este ejemplo, vaya a www.adobe.com/go/learn_programmingAS3samples_flash_es. Los archivos de la aplicación FileIO se encuentran en la carpeta Samples/FileIO. La aplicación consta de los siguientes archivos:

Archivo	Descripción
FileIO.fla o FileIO.mxml	El archivo de aplicación principal en Flash (FLA) o Flex (MXML).
com/example/programmingas3/fileio/FileDownload.as	Una clase que incluye métodos para descargar archivos de un servidor.
com/example/programmingas3/fileio/FileUpload.as	Una clase que incluye métodos para cargar archivos en un servidor.

Subtemas

Información general de la aplicación FileIO

La aplicación FileIO contiene la interfaz de usuario que permite a un usuario cargar o descargar archivos con Flash Player. En primer lugar, la aplicación define un par de componentes personalizados, FileUpload y FileDownload, que se encuentran en el paquete com.example.programmingas3.fileio. Cuando cada componente personalizado distribuye su evento contentComplete, se llama al método init() del componente y pasa referencias a una instancia de los componentes ProgressBar y Button, que permite a los usuarios ver el progreso de la carga o descarga del archivo, o cancelar la transferencia de archivos en curso.

A continuación se muestra el código relevante del archivo FileIO.mxml (hay que tener en cuenta que en la versión de Flash, el archivo FLA contiene componentes colocados en el escenario cuyos nombres coinciden con los de los componentes Flex descritos en este paso):

<example:FileUpload id="fileUpload" creationComplete="fileUpload.init(uploadProgress, cancelUpload);" />
<example:FileDownload id="fileDownload" creationComplete="fileDownload.init(downloadProgress, cancelDownload);" />

El siguiente código muestra el panel de carga de archivos (Upload File), que contiene una barra de progreso y dos botones. El primero botón, startUpload, llama al método FileUpload.startUpload(), que llama al método FileReference.browse(). El siguiente fragmento de código corresponde al panel Upload File:

<mx:Panel title="Upload File" paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">
    <mx:ProgressBar id="uploadProgress" label="" mode="manual" />
    <mx:ControlBar horizontalAlign="right">
        <mx:Button id="startUpload" label="Upload..." click="fileUpload.startUpload();" />
        <mx:Button id="cancelUpload" label="Cancel" click="fileUpload.cancelUpload();" enabled="false" />
    </mx:ControlBar>
</mx:Panel>

Este código coloca una instancia del componente ProgressBar y dos instancias del componente Button en el escenario. Cuando el usuario hace clic en el botón de carga (startUpload), se abre un cuadro de diálogo del sistema operativo, que permite al usuario seleccionar un archivo para cargarlo en un servidor remoto. El otro botón, cancelUpload, está desactivado de forma predeterminada; cuando un usuario inicia la carga de un archivo, el botón se activa y permite al usuario cancelar la transferencia del archivo en cualquier momento.

El código correspondiente al panel de descarga de archivos (Download File) es el siguiente:

<mx:Panel title="Download File" paddingTop="10" paddingBottom="10" paddingLeft="10" paddingRight="10">
    <mx:ProgressBar id="downloadProgress" label="" mode="manual" />
    <mx:ControlBar horizontalAlign="right">
        <mx:Button id="startDownload" label="Download..." click="fileDownload.startDownload();" />
        <mx:Button id="cancelDownload" label="Cancel" click="fileDownload.cancelDownload();" enabled="false" />
    </mx:ControlBar>
</mx:Panel>

Este código es muy similar al código para cargar archivos. Cuando el usuario hace clic en el botón de descarga, (startDownload), se llama al método FileDownload.startDownload(), que inicia la descarga del archivo especificado en la variable FileDownload.DOWNLOAD_URL. La barra de progreso, que se actualiza a medida que avanza la descarga del archivo, muestra el porcentaje del archivo que se ha descargado. El usuario puede cancelar la descarga en cualquier momento haciendo clic en el botón cancelDownload, que detiene inmediatamente la descarga del archivo en curso.

Descarga de archivos de un servidor remoto

La descarga de archivos de un servidor remoto se controla mediante la clase flash.net.FileReference y la clase personalizada com.example.programmingas3.fileio.FileDownload. Cuando el usuario hace clic en el botón de descarga, Flash Player inicia la descarga del archivo especificado en la variable DOWNLOAD_URL de la clase FileDownload.

La clase FileDownload define cuatro variables en el paquete com.example.programmingas3.fileio, como se muestra en el siguiente código:

    /**
     * Especificar en el código el URL del archivo que se descargará en el equipo del usuario.
     */
    private const DOWNLOAD_URL:String = "http://www.yourdomain.com/file_to_download.zip";

    /**
     * Crear una instancia de FileReference para controlar la descarga de archivos.
     */
    private var fr:FileReference;

    /**
     * Definir la referencia al componente ProgressBar de descarga.
     */
    private var pb:ProgressBar;

    /**
     * Definir la referencia al botón "Cancel" que detendrá inmediatamente
     * la descarga en curso.
     */
    private var btn:Button;

La primera variable, DOWNLOAD_URL, contiene la ruta de acceso al archivo, que se descarga en el equipo del usuario cuando éste hace clic en el botón de descarga, en el archivo de la aplicación principal.

La segunda variable, fr, es un objeto FileReference que se inicializa en el método FileDownload.init() y que controla la descarga del archivo remoto en el equipo del usuario.

Las dos últimas variables, pb y btn, contienen referencias a las instancias de los componentes ProgressBar y Button en el escenario, que se inicializan con el método FileDownload.init().

Inicialización del componente FileDownload

El componente FileDownload se inicializa mediante una llamada al método init() en la clase FileDownload. Este método utiliza dos parámetros, pb y btn, que son instancias de los componentes ProgressBar y Button, respectivamente.

    /**
     * Definir las referencias a los componentes y añadir detectores de los eventos OPEN, 
     * PROGRESS y COMPLETE.
     */
    public function init(pb:ProgressBar, btn:Button):void
    {
        // Definir las referencias a la barra de progreso y al botón de cancelación,
        // que se pasan desde el script que realiza la llamada.
        this.pb = pb;
        this.btn = btn;

        fr = new FileReference();
        fr.addEventListener(Event.OPEN, openHandler);
        fr.addEventListener(ProgressEvent.PROGRESS, progressHandler);
        fr.addEventListener(Event.COMPLETE, completeHandler);
    }

Inicio de la descarga de archivos

Cuando el usuario hace clic en la instancia del componente Download Button en el escenario, el método startDownload() inicia el proceso de descarga de archivos. El siguiente fragmento de código muestra el método startDownload():

    /**
     * Iniciar la descarga del archivo especificado en la constante DOWNLOAD_URL.
     */
    public function startDownload():void
    {
        var request:URLRequest = new URLRequest();
        request.url = DOWNLOAD_URL;
        fr.download(request);
    }

En primer lugar, el método startDownload() crea un nuevo objeto URLRequest y establece el URL de destino en el valor especificado por la variable DOWNLOAD_URL. A continuación, se llama al método FileReference.download() y el objeto URLRequest recién creado se pasa como un parámetro. Como consecuencia, el sistema operativo muestra un cuadro de diálogo en el equipo del usuario, donde le pide que seleccione una ubicación para guardar el documento solicitado. Cuando el usuario ha seleccionado una ubicación, se distribuye el evento open (Event.OPEN) y se llama al método openHandler().

El método openHandler() establece el formato de texto de la propiedad label del componente ProgressBar y activa el botón de cancelación, que permite al usuario detener inmediatamente la descarga en curso. La sintaxis del método openHandler() es la siguiente:

    /**
     * Cuando se ha distribuido el evento OPEN, cambiar etiqueta de la barra de progreso 
     * y activar el botón "Cancel", que permite al usuario cancelar la 
     * operación de descarga.
     */
    private function openHandler(event:Event):void
    {
        pb.label = "DOWNLOADING %3%%";
        btn.enabled = true;
    }

Supervisión del progreso de descarga de un archivo

Cuando un archivo se descarga desde un servidor remoto en el equipo del usuario, el evento progress (ProgressEvent.PROGRESS) se distribuye en intervalos regulares. Cuando se distribuye el evento progress, se llama al método progressHandler() y se actualiza la instancia del componente ProgressBar en el escenario. El código correspondiente al método progressHandler() es el siguiente:

    /**
     * Mientras se descarga el archivo, actualizar el estado de la barra de progreso.
     */
    private function progressHandler(event:ProgressEvent):void
    {
        pb.setProgress(event.bytesLoaded, event.bytesTotal);
    }

El evento progress contiene dos propiedades, bytesLoaded y bytesTotal, que se utilizan para actualizar el componente ProgressBar en el escenario. De esta forma, el usuario puede saber la cantidad de archivo que ya se ha descargado y la que queda por descargar. El usuario puede cancelar la transferencia del archivo en cualquier momento haciendo clic en el botón de cancelación situado bajo la barra de progreso.

Si el archivo se descarga correctamente, el evento complete (Event.COMPLETE) llama al método completeHandler(), que notifica al usuario que ha finalizado la descarga del archivo y desactiva el botón de cancelación. El código correspondiente al método completeHandler() es el siguiente:

    /**
     * Cuando finalice la descarga, cambiar la etiqueta de la barra de progreso 
     * por última vez y desactivar el botón "Cancel" porque la descarga 
     * ha finalizado.
     */
    private function completeHandler(event:Event):void
    {
        pb.label = "DOWNLOAD COMPLETE";
        btn.enabled = false;
    }

Cancelación de una descarga de archivos

Un usuario puede cancelar una transferencia de archivos y detener la descarga de más bytes en cualquier momento haciendo clic en el botón de cancelación en el escenario. El siguiente fragmento de código muestra la cancelación de una descarga:

    /**
     * Cancelar la descarga de archivo actual.
     */
    public function cancelDownload():void
    {
        fr.cancel();
        pb.label = "DOWNLOAD CANCELLED";
        btn.enabled = false;
    }

En primer lugar, el código detiene inmediatamente la transferencia del archivo, evitando que se descarguen más datos. A continuación, la propiedad de la etiqueta de la barra de progreso se actualiza para notificar al usuario que la descarga se ha cancelado correctamente. Finalmente, se desactiva el botón de cancelación, que evita que el usuario haga clic nuevamente en el botón hasta se intente volver a descargar el archivo.

Carga de archivos en un servidor remoto

El proceso de carga de archivos es muy similar al proceso de descarga de archivos. La clase FileUpload declara las mismas cuatro variables, como se muestra en el siguiente código:

private const UPLOAD_URL:String = "http://www.yourdomain.com/your_upload_script.cfm";
private var fr:FileReference;
private var pb:ProgressBar;
private var btn:Button;

A diferencia de la variable FileDownload.DOWNLOAD_URL, la variable UPLOAD_URL contiene el URL correspondiente al script de servidor que cargará el archivo desde el equipo del usuario. Las tres variables restantes se comportan del mismo modo que las variables correspondientes de la clase FileDownload.

Inicialización del componente FileUpload

El componente FileUpload contiene un método init(), al que se llama desde la aplicación principal. Este método utiliza dos parámetros, pb y btn, que son referencias a las instancias de los componentes ProgressBar y Button en el escenario. A continuación, el método init() inicializa el objeto FileReference definido previamente en la clase FileUpload. Finalmente, el método asigna cuatro detectores de eventos al objeto FileReference. El código correspondiente al método init() es el siguiente:

public function init(pb:ProgressBar, btn:Button):void
{
    this.pb = pb;
    this.btn = btn;

    fr = new FileReference();
    fr.addEventListener(Event.SELECT, selectHandler);
    fr.addEventListener(Event.OPEN, openHandler);
    fr.addEventListener(ProgressEvent.PROGRESS, progressHandler);
    fr.addEventListener(Event.COMPLETE, completeHandler);
}

Inicio de la carga de archivos

La carga de archivos se inicia cuando el usuario hace clic en el botón de carga en el escenario, que llama al método FileUpload.startUpload(). Este método llama al método browse() de la clase FileReference, lo que provoca que se abra un cuadro de diálogo del sistema operativo, donde se pide al usuario que seleccione un archivo para cargarlo en un servidor remoto. El siguiente fragmento de código muestra el método startUpload():

public function startUpload():void
{
    fr.browse();
}

Cuando el usuario selecciona un archivo para cargar, se distribuye el evento select (Event.SELECT), que provoca una llamada al método selectHandler(). El método selectHandler() crea un nuevo objeto URLRequest y establece la propiedad URLRequest.url en el valor de la constante UPLOAD_URL definida previamente en el código. Finalmente, el objeto FileReference carga el archivo seleccionado en el script de servidor especificado. El código correspondiente al método selectHandler() es el siguiente:

private function selectHandler(event:Event):void
{
    var request:URLRequest = new URLRequest();
    request.url = UPLOAD_URL;
    fr.upload(request);
}

El código restante de la clase FileUpload es el mismo código definido en la clase FileDownload. Si un usuario desea interrumpir la descarga en cualquier momento, puede hacer clic en el botón de cancelación, que establece la etiqueta de la barra de progreso y detiene inmediatamente la transferencia del archivo. La barra de progreso se actualiza siempre que se distribuye el evento progress (ProgressEvent.PROGRESS). De forma similar, cuando ha finalizado la carga, la barra de progreso se actualiza para notificar al usuario que el archivo se ha cargado correctamente. El botón de cancelación se desactiva hasta que el usuario inicie una nueva transferencia de archivos.