what is the difference between a collection singleton or instance within Titanium?

Question

In the Alloy docs, it mentions you can have a singleton or instance of a collection. You define one way or another using the instance tag:

<Alloy>
    <Collection id="localLibrary" src="book" instance="true"/>
    <Window>
        <TableView id="table" />
    </Window>
</Alloy>

I understand the general idea behind a singleton vs instance... but I do not understand the direct advantage/application of exposing it one way or another to the controller.

Specifically, what is the difference between this controller code:

var library = Alloy.Collections.book;
library.fetch();

and this controller code:

var library = $.localLibrary;
library.fetch();

Is it saying "grab all" instead of "grab just this one?"

Any clarification would be great, tia.

Answer 1

The difference is that Alloy.Collections.instance("book") will create a global singleton instance (Or returns an existing...) which means that you will be able to access it in all your controllers using Alloy.Collections.book. You can do the exactly same thing with Models.

Why would you do this? I think it is quite useful if you can access and manipulate with a data that are already loaded for instance in a TableView in the first window while you are somewhere in a sub window...

Globally Accessible Singleton:

var library = Alloy.Collections.book; // <Collection src="book"/>
    library.fetch();

Local Instance:

var library = $.localLibrary; // <Collection id="localLibrary" src="book" instance="true"/>
    library.fetch();