HACKING/architecture/Collections.txt

0001 Collection Architecture
0002 -----------------------
0003
0004 Collection is a container for a set of objects that collectively provider tracks to the application.
0005 It does this by providing Meta::Base derieved objects via the QueryMaker (which every collection has).
0006
0007 On plugin load a CollectionFactory is registered with CollectionManager which listens to the
0008 newCollection() signal. CollectionManager is responsible for integrating the new Collection within
0009 the rest of the application. Collection makes user visible strings, icons and other information
0010 available for the UI to use.
0011
0012 TrackProvider actually creates the Meta::Track objects using trackForUrl() which has a specially
0013 formatted URL that is unique accross application settings. A collection has it's own URL protocol
0014 which all uidUrl's of the collection's tracks start with.
0015
0016 For getting tracks according to metadata or statistical information each Collection has a QueryMaker
0017 implementation. Any component can get an instance of this specialized QueryMaker using Collection::queryMaker().
0018 CollectionManager has a special QueryMaker that will return results of all the registered collections
0019 using their queryMaker(). Use this if you want a track resolved without caring about it's origin.
0020
0021 TrackProvider and QueryMakers can be used seperatly from the collections. In practice though you'll
0022 find only TrackProvider getting used by Services and the filesystem browser. If needing to combinine
0023 it with a QueryMaker you are probably creating a Collection anyway.
0024 Also note that Collection objects don't use shared pointers so they are not especially well protected
0025 against getting removed. Holding the pointer to a QueryMaker for a prolonged amount of time
0026 invites problems (e.g. when the usb device is removed. We had a number of bugs for this)
0027