nsIDownloadManager replaced by Downloads.jsm

[Paolo Amadini]

Hello,

if you are maintaining an add-on or a Mozilla product that interacts
with downloads, you should look into updating your code to use the new
Downloads.jsm module instead of nsIDownloadManager as soon as possible.

While other Mozilla products may migrate at different times, Firefox
for Desktop will do so starting from version 26, meaning that add-ons
that use methods of nsIDownloadManager will no longer be compatible
unless updated. Firefox 26 will reach the Beta channel on October 29th,
and will go to release on December 10th, 2013.

*Overview*

We have been working on this new module over the past few months, with
the goal of eliminating any temporary unresponsiveness that could be
observed when downloads are started, as well as making the browser more
responsive in general while there are downloads in progress.

To make this possible, we removed all access to the "downloads.sqlite"
database, replacing it with an in-memory representation of the state
of current downloads. In Firefox for Desktop, the history of past
downloads is handled separately, using the "places.sqlite" database.

*Changes*

The new API is fully asynchronous and works somewhat differently from
the old one. It has the advantage of being designed for JavaScript from
the start, and is much simpler than the old XPCOM API. In particular,
listing and handling current downloads may be done using JavaScript
objects, without any special code for database access.

The complete documentation of the module can be found here:

https://developer.mozilla.org/Mozilla/JavaScript_code_modules/Downloads.jsm

We may still update existing methods to address specific needs or
new requirements, but the general mechanisms will remain the same.

*Testing*

A new about:config preference named "browser.download.useJSTransfer"
enables the browser and the Downloads Panel to use the Downloads.jsm
module instead of nsIDownloadManager as the back-end. The browser must
be restarted for the preference to take effect.

Support for this preference will be available in Nightly today or
tomorrow. This means that it will be ready for testing in the Aurora
channel starting from version 25, on August 8th.

In the Firefox 26 release train, nsIDownloadManager will not be used
anymore. The preference will be removed and there will be no way to
revert to the old system that caused potential performance issues.
We will finally be able to remove a lot of front-end code that is
complex to maintain and only needed for backwards compatibility.

*Feedback*

The version of the module in Firefox 25 is still in development, and
while the interface is complete, some features like restoring downloads
after a restart and the related prompts are not implemented yet. The
remaining work is tracked with dependencies of bug 847863:

https://bugzilla.mozilla.org/showdependencytree.cgi?id=847863&hide_resolved=1

If you notice any unexpected behavior with the new preference that is
not already listed there, feel free to file a new bug and mark it as
blocking bug 847863. For any other question or need, feel free to
reply to this thread in the relevant list (extensions or platform),
or contact myself directly. Any relevant information emerging from
the discussion will be summarized in a new project update.

Cheers,
Paolo

[Neil]

Paolo Amadini wrote:

>The complete documentation of the module can be found here:
>
>https://developer.mozilla.org/Mozilla/JavaScript_code_modules/Downloads.jsm
>
>

... plus you'll need all the subpages for the other objects of course.

Do I have to watch the download lists globally in order to find out
about new downloads (e.g. from content-disposition: attachment)?

Do I have to emulate cleanUp by calling remove() on all the completed
downloads?

Do I have to maintain the active download count myself? (I don't think
that would be a problem.)

Does Downloads.createDownload(aFailedDownload) replace
aFailedDownload.retry()?

How do I watch for changes to a download if I don't know whether or not
it's part of a download list? (But given the first answer, it looks like
I have to watch the list whether I like it or not, and then filter on
the download in which I'm interested.)

P.S. I hope the misspelling of succeeded is a documentation error.

--
Warning: May contain traces of nuts.

[David E. Ross]

Will this break the Preserve Download Modification Timestamp extension
at <https://addons.mozilla.org/en-US/seamonkey/addon/222517/>?

--
David E. Ross
<http://www.rossde.com/>

Concerned about someone (e.g., the government)
snooping into your E-mail? Use PGP.
See my <http://www.rossde.com/PGP/>

[Paolo Amadini]

On 03/08/2013 17.26, Neil wrote:
> Do I have to watch the download lists globally in order to find out
> about new downloads (e.g. from content-disposition: attachment)?

Yes, you should add a view to the public and private download lists.

> Do I have to emulate cleanUp by calling remove() on all the completed
> downloads?

Good point. While you could do that for now, we'll likely add a method
to the DownloadList object, since it's an existing use case. Just filed
bug 901262.

> Do I have to maintain the active download count myself? (I don't think
> that would be a problem.)

Yes, as there are different counts that consumers may want to track.

> Does Downloads.createDownload(aFailedDownload) replace
> aFailedDownload.retry()?

No, it's replaced by aFailedDownload.start().

> How do I watch for changes to a download if I don't know whether or not
> it's part of a download list? (But given the first answer, it looks like
> I have to watch the list whether I like it or not, and then filter on
> the download in which I'm interested.)

If a download is not part of a DownloadList, it means it doesn't appear
in the user interface and is functional to some other part of the code,
and you cannot watch it (similar to the current situation when using
nsIWebBrowserPersist without linking it to an nsITransfer).

> P.S. I hope the misspelling of succeeded is a documentation error.

Fixed, thanks!

I'll use some of these questions as the base for a more detailed
migration documentation.

Paolo

[Paolo Amadini]

On 03/08/2013 19.27, David E. Ross wrote:
> Will this break the Preserve Download Modification Timestamp extension
> at <https://addons.mozilla.org/en-US/seamonkey/addon/222517/>?

Quite likely. In the new API we'll probably need to add explicit
support for this use case, something like a hook of some kind to
DownloadCopySaver and DownloadLegacySaver.

My suggestion to the add-on author would be to file a bug under the
Extension Compatibility component, blocking the more general bug 825588
for the Downloads API, with as much details as possible, and we'll get
to it as soon as the rest of the feature set is complete.

https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Extension%20Compatibility

Cheers,
Paolo

[Neil]

Paolo Amadini wrote:

>On 03/08/2013 17.26, Neil wrote:
>
>
>>Do I have to watch the download lists globally in order to find out about new downloads (e.g. from content-disposition: attachment)?
>>
>>
>Yes, you should add a view to the public and private download lists.
>
>

So nsIDownloadManagerUI is going away too?

>>Does Downloads.createDownload(aFailedDownload) replace aFailedDownload.retry()?
>>
>>
>No, it's replaced by aFailedDownload.start().
>
>

Sorry, I'd misread the note there. Thanks for clearing that up.

>I'll use some of these questions as the base for a more detailed migration documentation.
>
>

Or you could just edit the MDN pages for the interfaces that are being
removed and link to the replacements for all the relevant methods...

[Paolo Amadini]

On 04/08/2013 1.42, Neil wrote:
> So nsIDownloadManagerUI is going away too?

The Downloads back-end will not call any method of nsIDownloadManagerUI
anymore, new downloads should be detected using views. Technically, the
interface will still be there for a short time until we refactor the
code that opens the user interface (the Library window or the Downloads
tab in Firefox for Desktop).

> Or you could just edit the MDN pages for the interfaces that are being
> removed and link to the replacements for all the relevant methods...

Good idea, will do that also.

Cheers,
Paolo

[Robert Kaiser]

Paolo Amadini schrieb:

> The Downloads back-end will not call any method of nsIDownloadManagerUI
> anymore

So I cannot implement an alternative download manager any more?

Robert Kaiser

[Paolo Amadini]

You can for sure :-) Anything we're changing and has a valid use case
will still be implemented in new ways, hopefully simpler to hook into.

Paolo

[Neil]

Paolo Amadini wrote:

>A new about:config preference named "browser.download.useJSTransfer" enables the browser and the Downloads Panel to use the Downloads.jsm module instead of nsIDownloadManager as the back-end. The browser must be restarted for the preference to take effect.
>
>Support for this preference will be available in Nightly today or tomorrow. This means that it will be ready for testing in the Aurora channel starting from version 25, on August 8th.
>
>In the Firefox 26 release train, nsIDownloadManager will not be used anymore. The preference will be removed and there will be no way to revert to the old system that caused potential performance issues. We will finally be able to remove a lot of front-end code that is complex to maintain and only needed for backwards compatibility.
>
>

I notice that this preference exists entirely in browser front-end code.
So how are other Mozilla products expected to test Downloads.jsm?

[Paolo Amadini]

On 16/08/2013 10.22, Neil wrote:
> Paolo Amadini wrote:
>> A new about:config preference named "browser.download.useJSTransfer"
>> enables the browser and the Downloads Panel to use the Downloads.jsm
>> module instead of nsIDownloadManager as the back-end. The browser must
>> be restarted for the preference to take effect.
>>

> I notice that this preference exists entirely in browser front-end code.
> So how are other Mozilla products expected to test Downloads.jsm?

The API itself can be used without changing the preference at all, if
you add items to the DownloadList using its methods. To switch downloads
started from content to use the new API, you should register its
nsITransfer component during "profile-after-change":

const cid = Components.ID("{1b4c85df-cbdd-4bb6-b04e-613caece083c}");
Components.manager.QueryInterface(Ci.nsIComponentRegistrar)
.registerFactory(cid, "", "@mozilla.org/transfer;1",
null);

http://mxr.mozilla.org/mozilla-central/source/browser/components/downloads/src/DownloadsStartup.js#96

At some point, we'll add a build-time switch to enable this component.

Cheers,
Paolo

[Eric Shepherd]

On 2013-08-03 12:21:57 +0000, Paolo Amadini said:

> The complete documentation of the module can be found here:
>
> https://developer.mozilla.org/Mozilla/JavaScript_code_modules/Downloads.jsm

Paulo: On behalf of the documentation team, I want to thank you for
documenting this! We always appreciate it when the people who best know
new features and technologies are active in the documentation process,
and creating the docs like this is the absolute most effective way to
do that.

That you also went for it and documented Promise.jsm while you were at
it is a wonderful bonus.

You win the coveted Hero of the MDN Team award!

--
Eric Shepherd
Developer Documentation Lead
Mozilla
Blog: http://www.bitstampede.com/
Twitter: @sheppy

[dis...@gmail.com]

Hi,

Is there a way to detect which Firefox window a Download "belongs to" in onDownloadAdded/onDownloadChanged methods? Using DownloadSource.referrer property does not seem to be a reliable way.

Another question: is it possible to add some kind of 'id' property to Download object which can be safely passed, say, to our Javascript XPCOM object or worker thread?

--
Denis

[Paolo Amadini]

On 18/09/2013 9.13, dis...@gmail.com wrote:
> Is there a way to detect which Firefox window a Download "belongs to" in onDownloadAdded/onDownloadChanged methods? Using DownloadSource.referrer property does not seem to be a reliable way.

No, the Download object is global for all windows.

> Another question: is it possible to add some kind of 'id' property to Download object which can be safely passed, say, to our Javascript XPCOM object or worker thread?

To associate properties with a Download object, the recommended way is
to use a Map or a WeakMap. With that technique, you can associate your
own numeric identifier if needed, or other properties directly.

Note that such properties are not persisted across sessions. If you
need to do that, or have any other feature request for an add-on you're
writing, you can file a bug blocking bug 907764, specifying the use
case you're trying to solve:

https://bugzilla.mozilla.org/enter_bug.cgi?product=Firefox&component=Extension%20Compatibility&blocked=907764

Cheers,
Paolo

[dis...@gmail.com]

> > Is there a way to detect which Firefox window a Download "belongs to" in onDownloadAdded/onDownloadChanged methods? Using DownloadSource.referrer property does not seem to be a reliable way.
>
>
> No, the Download object is global for all windows.
>

Thanks for quick replay.

I might have used inappropriate wording: "belongs to". For our extension it is very important to know the window that initiated download. Is it possible?

[melch...@gmail.com]

Oooh... cool.. making it simpler and more efficient? O_o

Read the new comment I made(making) on that bug-report 847863 when you have a sec..