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
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list http://lists.osafoundation.org/mailman/listinfo/dev
