Proposing ObjectManager interface

[David Zeuthen]

On Mon, Feb 28, 2011 at 5:40 AM, Simon McVittie
<simon.mcvittie at collabora.co.uk> wrote:
> On Sun, 27 Feb 2011 at 07:28:20 -0500, David Zeuthen wrote:
>> Concretely, what I'm proposing is that we add this interface to the spec
>>
>>   <interface name="org.freedesktop.DBus.ObjectManager">
>>     <method name="GetAll">
>>       <arg type="a(oa(sa{sv}))"
>> name="object_paths_interfaces_and_properties" direction="out"/>
>>     </method>
>
> Presumably the best-practice use for this interface would be that in APIs
> where clients might want to not look at every single object, there's an
> alternative way to get the list of objects; and that in high-level APIs,
> this interface is used by default but can be suppressed, similar to GDBus'
> bindings for PropertiesChanged?
>
> (Thinking here of Telepathy: AccountManager should clearly be an ObjectManager
> for Account instances, but if Connection is an ObjectManager for Channel
> instances, getting the full list of Channels is basically a waste of time
> unless you're either Mission Control or a debugging tool; most Telepathy
> clients only interact with a relatively small subset of channels.)

I think including flags dictating the behavior etc. would complicate
this (I'm fine with having an unused flags parameter though for
future-proofing etc.). The guidance would be that you can use
ObjectManager for one or more forests of objects in your app (possibly
all objects) - typically objects that you expect all clients to want
to use. Just like the guidance for properties is more or less "use a
:Xyz property if you expect everyone to read/use it and it's small -
use a GetXyz() method otherwise (that's the guidance I use anyway,
it's not really spelled out anywhere).

IOW, I don't want ObjectManager to be the be-all-end-all way of
enumerating objects...

>>     <signal name="InterfacesAdded">
>>       <arg type="o" name="object_path"/>
>>       <arg type="a(sa{sv})" name="interfaces_and_properties"/>
>>     </signal>
>
> Do you have a way to represent "this object disappeared" in this API, or are
> clients meant to infer that from all of its interfaces disappearing?

The idea was the latter. Which we can do because the API is relatively
simple and don't have a recurse=TRUE or not.

> If a parent object manages two unrelated classes of child (contrived example:
> if UPower is an ObjectManager for PowerSupply but also an ObjectManager for
> Alert), are clients meant to distinguish between them by looking for
> well-known interfaces, or is this forbidden or discouraged?

I think it's fine for clients to look at what interfaces the object
implements. Or what the object path is. I don't want use to be too
specific in the spec and I don't think any specific guidance is
warranted.

> I think also points to an ambiguity in our (de facto) object model: can
> objects that already exist gain and lose interfaces?
>
> By "our object model" I mean the subset of D-Bus message passing that
> high-level APIs (including bindings like dbus-glib and reimplementations like
> GDBus) are expected to provide "nice" object-oriented API for.
>
> In Telepathy, Connections can gain interfaces when they become CONNECTED and
> discover more about the server's capabilities, but they can never lose
> interfaces (to ensure that when you call a method you think is valid, it's
> still there, even if it just gives you a NotImplemented error), and our other
> objects can't gain or lose interfaces at all.

I would like this to be encouraged in D-Bus. The ObjectManager API
certainly encourages this behavior.

>>   This
>>   signal contains all properties for the added interfaces.
>
> Mutable or immutable properties? (In other words, can you only be a sensible
> ObjectManager if the objects you manage implement PropertiesChanged for all
> their mutable properties? IMO that'd be reasonable, but deserves saying.)

The way the GDBus ObjectManager proxy implementation works here is
that it's orthogonal to ObjectManager. For example, if you have a
Chatroom interface where the "String[] Participants" property doesn't
emit PropertiesChanged but there's ParticipantJoined(String name),
ParticipantLeft(String name) signals then you can easily write a
GDBusProxy subclass that intercepts these signals and locally
maintains the Participants property so the user doesn't even know
about the implementation-detail that is that the Participants property
doesn't emit the PropertiesChanged signal. You can use this with
GDBusProxyManager since you supply

 http://people.freedesktop.org/~david/gdbus-binding-tool-20100902/GDBusProxyManager.html#GDBusProxyTypeFunc

yourself. So, yeah, this question is orthogonal to ObjectManager. So I
don't think the D-Bus spec should need to discuss this and I think the
guidance we are giving (if any) shouldn't address it either. The
answer to your question is the same as for "what should GetAll()
return"....

Thanks,
David