[Dev] Overview of Item lookup mechanisms

[Morgen Sagen]

Yesterday there was some discussion on #chandler about different  
methods for accessing "well known" items; example items include: the  
Contact item that represents "Me", the "current/default" IMAPAccount  
item, and the outermost CPIA Block item.  Before we try to propose a  
new method, or standardize on an existing one, I thought I should recap  
what's currently in place.

Currently we have four different mechanisms for finding these:

1) using a repository path (such as '//userdata/me' ),
2) using what I call a "CurrentPointer" item, and
3) CPIA's findBlockByName method (which I believe maps names to UUIDs  
in a dict)
4) The ParcelManager's lookup( ) method

Method 1 is pretty straightforward and guarantees uniqueness (since the  
repository enforces "no siblings with the same name"), but isn't really  
suited for the case where you can have multiple instances of a Kind,  
you want to designate one of those instances as the current (or  
default) one, yet you also want to allow the user to override the  
default in their own parcel.  That's where method 2 comes in:  I added  
a simple Kind called CurrentPointer [1] which has a single attribute  
called "item" (inverse attribute = "currentItemOf").  Right now,  
instances of CurrentPointer live in a "well known" location:  
//parcels/osaf/current/ so they can be found easily (we can change this  
location if it makes sense).  Their use is probably best described by  
example:

We ship Chandler with several WebDAV accounts prepopulated, with one of  
them designated the "default" WebDAV account.  To do this, I define a  
CurrentPointer item named WebDAVAccount in //parcels/osaf/current/ .   
When I define the WebDAV account items themselves, the account I want  
to be the default has its "currentItemOf" attribute set to the  
WebDAVAccount CurrentPointer item.  Through the magic of bi-directional  
references, that CurrentPointer item also now points back  to my  
default item.  Where this really comes in handy is when I define my own  
WebDAV Account in a personal (external) parcel -- which is guaranteed  
to be processed *after* the "internal" parcels are loaded: my own  
account that I want to designate the default has its "currentItemOf"  
attribute point to the WebDAVAccount CurrentPointer item, and the  
bi-di-ref now points to mine instead of the one shipped within  
Chandler.

There is a simple package (osaf.current) which takes care of accessing  
these "current pointers" from Python:

     accountItem = Current.get(view, "WebDAVAccount")
     Current.set(view, "WebDAVAccount", accountItem)
     if Current.isCurrent(view, "WebDAVAccount", accountItem): ...

I think I will probably switch the //userdata/me Contact over to using  
the current pointer mechanism.  It seems to me that CPIA could also use  
this to find the top-level Block to render -- changing skins would mean  
setting a new Block as the current top level Block.  This would allow a  
user to override the top-level Block with their own from their parcel.

John would have to explain Method 3.

Method 4 is something the ParcelManager uses to find items in parcels  
(although any code could make use of this).  Each parcel has an  
associated namespace name (either explicitly defined within a  
parcel.xml or inherited from a parent parcel).  The ParcelManager  
maintains a dictionary which maps these namespace names to a Parcel  
item.  In addition, each Parcel item can optionally have a mapping of  
names to child items.  The goal of this was to allow a "deep" parcel  
hierarchy to be "flattened", or to allow items to be rearranged (have  
their repository path change) without affecting how other parcels refer  
to those items.  The lookup( ) method is documented in epydoc [2].

So those are the item lookup mechanisms that I know about (I guess I  
should include lookup-via-UUID for completeness).  I believe in the  
future we will have a mechanism for creating multiple 'virtual'  
hierarchies by traversing ref collections -- which could reduce the  
need for some of the current mechanisms.

[1]  
http://o11n.org/docs/current/model/parcels/osaf/contentmodel/ 
CurrentPointer/
[2]  
http://o11n.org/docs/current/api/application.Parcel.Manager- 
class.html#lookup