Proposing ObjectManager interface

[Simon McVittie]

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.)

>     <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?

In Telepathy we've ended up with each of our major "class-like" interfaces
having a signal to indicate "I stopped existing" (usually with arguments
giving details of the reason the object went away), and some of our
ObjectManager-like classes also duplicate those signals for their children
(to avoid race conditions).

Perhaps the best-practice should be that the ObjectManager (if there is one)
signals the object's death, and if you have a proxy for the Object without
also having one for the ObjectManager, you detect its death by adding a signal
match to the ObjectManager's path, with arg0path as a filter?

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 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.

>   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.)

    S