I spent quite a while with Havoc last week looking over the Bigboard
applet's use of the data model, and discussing what the actual correct
usage should be.
First, some concepts:
"Ready State"
When the data model starts up, it may not yet be "ready". For example,
this is the case if the data model engine is in the process of
authenticating to online.gnome.org. Once the data model is "ready",
it is always ready.
The data model will reliably become ready within a fixed time, but
that implies nothing about what will be in the data model when
it becomes ready. In the worst case, when we can't connect to the
data model engine, the data model might be completely empty.
"Ready Notification"
A "ready notification" means that your application should start
fetching data from the data model. Ready notifications occur at two
times.
A) On initial startup, when the data model goes from not ready,
to ready.
B) On reconnection to online.gnome.org when we are already ready.
"Online"
When the data model is "online", this means that there is an active
connection to online.gnome.org. This is, means:
- We're actively receiving notifications on changes to data
- Updates made to online.gnome.org will likely get there.
Note that this is pretty something that you primarily want to reflect
in the user interface, by graying out actions, or showing an offline
indicator, not use to direct code flow. You can still retrieve
data from the data model when offline (via the cache). An update
made when online might fail for various reasons, one of them being
that the connection to online.gnome.org is lost after sending it
and before the reply is received.
"Connected"
This word is banned from our vocabulary, since we were using it for
at least three different things.
Exposure in the API
===================
The ready state is a property of the data model; in C, it's accessible:
ddm_data_model_is_ready()
In python as:
model.ready
Ready notifications are a GObject signal in C, called "ready", and
exposed in Python as:
model.[add/remove]_connected_handler()
The online state is part of the data model, available as:
online-desktop:/o/global#online
Application usage
=================
Before the model is in the ready state, an application should display
itself in a "neutral" state, neither online nor offline. One possible
way of doing this is by simply not displaying the application window at
all until the first ready notification. (This is more appropriate for a
desktop component than for something launched explicitly by the user;
the user should get immediate feedback when they explicitly launch an
application.)
When an application receives a "ready" notification, it should start
retrieving data from the data model. The two starting points are:
The online desktop global object
DDMDataResource *ddm_data_model_get_global_resource();
model.global_resource
The online.gnome.org object for the current user
DDMDataResource *ddm_data_model_get_self_resource();
model.self_resource
(This will be NULL/None if the user has never logged into
online.gnome.org)
For convenience, we guarantee that these never change between emissions
of 'ready'. To retrieve data, you need to do two things:
- Query for the data initially
- Connect to future changes to the data
In python, that looks like:
model.query_resource(model.self_resource, "contacts [name;photoUrl]")
model.self_resource.connect(self.on_contacts_changed, "contacts")
self.on_contacts_changed(model.self_resource)
Note that this is a little different than current usage since we don't
connect a reply handler to the query; we just use a change connection.
(Relates to
http://mail.gnome.org/archives/online-desktop-list/2007-October/msg00033.html)
It's legitimate to hold a reference to a resource object past a "ready
notification" (To hold onto a resource in C, you need to use
ddm_data_resource_ref()), but once the notification is received, the
object is stale and will never be updated again.
This normally works out fine ... since you are starting again from
scratch on the ready notification, any reference you might be holding to
resource objects will be replaced.
So, that's the basics of how I see things working.... some of the
details of the above may change as I go ahead and get it into place.
- Owen
P.S. - I'm not actually sure that the idea of multiple invocations of
"ready" is right in the long term, because it doesn't extend well to
the idea of the data engine connecting to multiple different servers
and presenting data from all of them. Perhaps the right model is
instead:
"global-resource-changed" ... model.global_resource has been
replaced because the app has reconnected to the data engine.
"self-resource-changed" ... model.self_resource has been
replaced because the data engine has reconnected to
online.gnome.org.
But I think it will work out for now.
Attachment:
signature.asc
Description: This is a digitally signed message part