Re: [Banshee-List] Meaning of Source class and its subclasses and Models

[Gabriel Burt <gabriel burt gmail com>]

2009/1/23 Eric Schultz <hammy charter net>:
> I'm trying to understand what certain classes do in Banshee. I'm very
> confused as to the purpose of the Source class and its subclasses like
> PrimarySource, LibrarySource and so on. What is it that a Source represents
> and what do they actually do? I guess a basic summary of its purposes and
> use would be helpful

Sources appear in the sources list (if registered with the
SourceManager), they can have a parent and/or children (Sources, all),
they have a name, an icon, have convenience methods for registering a
Message (eg like Last.fm does when you switch to a station).

DatabaseSource is a subclass that is all of the above but also holds a
collection of tracks via its DatabaseTrackListModel.  Playlists, Music
Library, Smart Playlists, Play Queue all derive from this.  It has
methods for efficiently adding/removing/rating tracks, and it has the
ability to have its list of tracks filtered by a search (user text
search) or a filter (the artist/album/podcast/new/downloaded
browsers).

PrimarySources subclass DatabaseSource, and are the 'owners' of
entries in the CoreTracks table.  So LibrarySources are a subclass of
them, but also DAAP sources, and DAP (iPod etc).  They know about
'remove from library', 'delete from disk', and about moving tracks
from one source to another (eg drag and drop).

LibrarySource is mostly just a PrimarySource whose tracks are
accessible via the normal filesystem api (as opposed to a MTP player
or DAAP).

Sources are defined in our Banshee.Services assembly, with zero
dependency on Gtk# - they are completely GUI agnostic.  They can be
combined with different views ("SourceContents") to show tracks lists,
DAP sync prefs, etc.

> I also don't understand what the BansheeModelCache does. Obviously it caches
> something in the database but what and when are they cached?

BansheeModelCache<T> is just a Hyena.Data.Sqlite.SqliteModelCache<T>
but with the two relevant table names predefined.  T is the generic
parameter, and is the object type being cached.  SqliteModelCache is
backed by two tables:

CREATE TABLE CoreCacheModels (
                    CacheID             INTEGER PRIMARY KEY,
                    ModelID             TEXT);

CREATE TABLE CoreCache (
                        OrderID INTEGER PRIMARY KEY,
                        ModelID INTEGER,
                        ItemID INTEGER);

A model in this sense is, say, the tracks for the Music Library, or
the artists for a certain Playlist.  Each one has a unique ModelId (eg
"SmartPlaylistSource-62-DatabaseTrackInfo" for smart playlist #62's
tracks) which is a string and maps to a number, the CacheId, through
the CacheModels table (so we can use the integer instead of the string
in the CoreCache table itself).

CoreCache is just used to store a subset of items (by their ItemId)
from a model (by its ModelId).  In practice, we use this, as an
example,  to store a sorted set of tracks that match a search.   Let
me elaborate:

The user searches for "title:foo", so we run a query like this (simplified):
INSERT INTO CoreCache (ModelID, ItemID) SELECT 14, TrackID From
CoreTracks WHERE Title like '%foo%' ORDER BY artist, album, title, etc

This assumes the CacheId for this set of tracks is 14.  Say there were
402 tracks that matched that search; we now have all 402 respective
TrackIds in CoreCache, presorted (by way of inserting them in order).
Now as the user scrolls down the list of results, we can pull the
track info from CoreTracks as needed (using LIMIT/OFFSET in our SQL
selects), but we can do it quickly because we don't have to resort or
refilter each time.  We do a query like this:

SELECT CoreTracks.* FROM CoreTracks, CoreCache WHERE TrackID = ItemID
ORDER BY OrderID LIMIT 20 OFFSET 100

In practice, for tracks, we select 5 times the number of rows
currently in the track list on each go - a middle ground between
selecting them all in one go and selecting only one.

I hope this helps.

Gabriel