Home

# Class goog.net.FileDownloader

A class for downloading remote files and storing them locally using the HTML5 filesystem API.

extends goog.Disposable

Instance Method Summary
| `cancel_(!goog.net.FileDownloader.Download_ download)` Abort the download of the given URL.

`disposeInternal()`

Deletes or nulls out any references to COM objects, DOM nodes, or other disposable objects. Classes that extend {@code goog.Disposable} should override this method. Not reentrant. To avoid calling it twice, it must only be called from the subclass' {@code disposeInternal} method. Everywhere else the public {@code dispose} method must be used. For example:

    mypackage.MyClass = function() {
    goog.base(this);
    // Constructor logic specific to MyClass.
    ...
    };
    goog.inherits(mypackage.MyClass, goog.Disposable);

    mypackage.MyClass.prototype.disposeInternal = function() {
    goog.base(this, 'disposeInternal');
    // Dispose logic specific to MyClass.
    ...
    };

`download(string url) ⇒ !goog.async.Deferred`

Download a remote file and save its contents to the filesystem. A given file is uniquely identified by its URL string; this means that the relative and absolute URLs for a single file are considered different for the purposes of the FileDownloader. Returns a Deferred that will contain the downloaded blob. If there's an error while downloading the URL, this Deferred will be passed the {@link goog.net.FileDownloader.Error} object as an errback. If a download is already in progress for the given URL, this will return the deferred blob for that download. If the URL has already been downloaded, this will fail once it tries to save the downloaded blob. When a download is in progress, all Deferreds returned for that download will be branches of a single parent. If all such branches are cancelled, or if one is cancelled with opt_deepCancel set, then the download will be cancelled as well.

| `error_(!goog.net.FileDownloader.Download_ download, ?goog.fs.Error= opt_err)` The error callback for all asynchronous operations. Ensures that all stages of a given download are cleaned up, and emits the error event.
| `fileSuccess_(!goog.net.FileDownloader.Download_ download, !goog.fs.FileEntry file)` The callback called when a file that will be used for saving a file is successfully opened.
| `fileWriterSuccess_(!goog.net.FileDownloader.Download_ download, !goog.fs.FileWriter writer)` The callback called when a file writer is succesfully created for writing a file to the filesystem.
| `freeXhr_(!goog.net.XhrIo xhr)` Remove all event listeners for an XHR and release it back into the pool.

`getDir_(string url, ?goog.fs.DirectoryEntry.Behavior behavior) ⇒ !goog.async.Deferred`

Get the directory for a given URL. If the directory already exists when this is called, it will contain exactly one file: the downloaded file. This not only calls the FileSystem API's getFile method, but attempts to distribute the files so that they don't overload the filesystem. The spec says directories can't contain more than 5000 files (http://www.w3.org/TR/file-system-api/#directories), so this ensures that each file is put into a subdirectory based on its SHA1 hash. All parameters are the same as in the FileSystem API's Entry#getFile method.

| `getDownloadedBlob(string url) ⇒ !goog.async.Deferred` Load a downloaded blob from the filesystem. Will fire a deferred error if the given URL has not yet been downloaded.
| `getFile_(string url) ⇒ !goog.async.Deferred` Get the file for a given URL. This will only retrieve files that have already been saved; it shouldn't be used for creating the file in the first place. This is because the filename isn't necessarily determined by the URL, but by the headers of the XHR response.

`getLocalUrl(string url) ⇒ !goog.async.Deferred`

Get the local filesystem: URL for a downloaded file. This is different from the blob: URL that's available from getDownloadedBlob(). If the end user accesses the filesystem: URL, the resulting file's name will be determined by the download filename as opposed to an arbitrary GUID. In addition, the filesystem: URL is connected to a filesystem location, so if the download is removed then that URL will become invalid. Warning: in Chrome 12, some filesystem: URLs are opened inline. This means that e.g. HTML pages given to the user via filesystem: URLs will be opened and processed by the browser.

| `getName_(!goog.net.XhrIo xhr) ⇒ string` Gets the filename specified by the XHR. This first attempts to parse the Content-Disposition header for a filename and, failing that, falls back on deriving the filename from the URL.
| `gotXhr_(!goog.net.FileDownloader.Download_ download, !goog.net.XhrIo xhr)` The callback called when an XHR becomes available from the XHR pool.
| `isDownloaded(string url) ⇒ !goog.async.Deferred` Return (deferred) whether or not a URL has been downloaded. Will fire a deferred error if something goes wrong when determining this.
| `isDownloading(string url) ⇒ boolean` Returns whether or not there is an active download for a given URL.
| `remove(string url) ⇒ !goog.async.Deferred` Remove a URL from the FileDownloader. This returns a Deferred. If the removal is completed successfully, its callback will be called without any value. If the removal fails, its errback will be called with the {@link goog.fs.Error}.
| `sanitize_(string str) ⇒ string` Sanitize a string so it can be safely used as a file or directory name for the FileSystem API.

`setBlob(string url, !Blob blob, string= opt_name) ⇒ !goog.async.Deferred`

Save a blob for a given URL. This works just as through the blob were downloaded form that URL, except you specify the blob and no HTTP request is made. If the URL is currently being downloaded, it's indeterminate whether the blob being set or the blob being downloaded will end up in the filesystem. Whichever one doesn't get saved will have an error. To ensure that one or the other takes precedence, use {@link #waitForDownload} to allow the download to complete before setting the blob.

| `urlToName_(string url) ⇒ string` Extracts the basename from a URL.
| `waitForDownload(string url) ⇒ !goog.async.Deferred` Return a Deferred that will fire once no download is active for a given URL. If there's no download active for that URL when this is called, the deferred will fire immediately; otherwise, it will fire once the download is complete, whether or not it succeeds.
| `writeEnd_(!goog.net.FileDownloader.Download_ download)` The callback called when file writing ends, whether or not it's successful.
| `xhrSuccess_(!goog.net.FileDownloader.Download_ download)` The callback called when an XHR succeeds in downloading a remote file.

Static Method Summary
| `Download_(string url, !goog.net.FileDownloader downloader)` A struct containing the data for a single download.