Bug 34869: Add ObjectManager interface to the spec - David Zeuthen (not reading bugmail) <zeuthen@gmail.com> - 3/1/2011 Back to Bug | Your Reviews | Help
Attachment 45484: Updated patch - David Zeuthen (not reading bugmail) <zeuthen@gmail.com> - 4/11/2011 (View )

Show Quick Help

From: David Zeuthen <davidz@redhat.com>
Date: Tue, 8 Mar 2011 10:41:26 -0500
Subject: [PATCH] Add org.freedesktop.DBus.ObjectManager interface
The org.freedesktop.DBus.ObjectManager provides a standardized and
efficient way of keeping one or more tree of objects synchronized
between one server and several clients.
https://bugs.freedesktop.org/show_bug.cgi?id=34869
Signed-off-by: David Zeuthen <davidz@redhat.com>
<Overall Comment>
Previous Reviews
Simon McVittie <smcv@collabora.com>
4/12/2011
Conceptually, this looks good. The details need a bit of adjustment.
doc/dbus-specification.xml
3001 
3002 <sect2 id="standard-interfaces-objectmanager">
3003 <title><literal>org.freedesktop.DBus.ObjectManager</literal></title>
3004 <para>
3005 An application can optionally make use of this interface to
I'd be tempted to say "An API can" instead, to emphasize that choosing whether to use ObjectManager is up to the D-Bus API designer, not the implementer (in cases where they might be different people, like Telepathy or MPRIS).
It might also be worth saying something like:
It is appropriate to use this interface if
users of the tree of objects are expected to
be interested in all interfaces of all objects in
the tree; a more granular API should be used if
users of the objects are expected to be interested
in a small subset of the objects, a small subset
of their interfaces, or both.
3009 call:
3010 </para>
3011 <para>
3012 <programlisting>
3013 org.freedesktop.DBus.ObjectManager.GetManagedObjects (out DICT&lt;OBJPATH,DICT&lt;STRING,DICT&lt;STRING,VARIANT&gt;&gt;&gt; objpath_interfaces_and_properties);
So, er, that's a{oa{sa{sv}}}? I thought Telepathy had intimidating data-types :-)
3015 </para>
3016 <para>
3017 The return value of this method is a dict whose keys are
3018 object paths. All returned object paths are children of the
3019 object path implementing this interface. Each value is a dict
I think this deserves clarification that they're syntactically children in the object-path tree, rather than some loose conceptual relationship:
... implementing this interface, i.e. their object
paths start with the ObjectManager's object path
plus '/'.
(At least, I assume that's what you meant.)
3021 containing the properties (see <xref
3022 linkend="standard-interfaces-properties"/>) for each interface
3023 and object path in question that the
3024 <literal>org.freedesktop.DBus.Properties.GetAll</literal>
3025 method would return. If an interface has no properties, the
This run-on sentence is rather awkward. How about:
Each value is a dict, whose keys are interface names.
Each value in this inner dict is the same dict that
would be returned by the <>...GetAll</> method for that
combination of object path and interface. If an
interface has no ...
(I deliberately put object path first here because that's the logical order: as seen in dbus-send, and (hopefully) in the libdbus and GDBus APIs, the hierarchy from largest to smallest is bus name, object path, interface, member.)
Does GetAll actually specifically say that it returns {} for a propertyless interface? If not, it should. (There's a dbus-glib bug about that.)
3038 </para>
3039 <para>
3040 The <literal>InterfacesAdded</literal> signal is emitted when
3041 either a new object is added or if an existing object gains
3042 one or more interfaces while the
Grammar: choose whether you're saying "when" or "if" (I vote for "when"). I'd say:
when either a new object is added, or an existing ...
I think this "while" deserves to be a sentence break.
3043 <literal>InterfacesRemoved</literal> signal is emitted
3044 whenever an object is removed or it loses one or more
3045 interfaces. The second parameter of the
3046 <literal>InterfacesAdded</literal> signal contains a dict with
3047 the interfaces and properties (if any) that has been added to
"that have been added": it's the interfaces and properties that were added, not the dict
3046 <literal>InterfacesAdded</literal> signal contains a dict with
3047 the interfaces and properties (if any) that has been added to
3048 the given object path. Similarly, the second parameter of the
3049 <literal>InterfacesRemoved</literal> signal contains an array
3050 of the interfaces that was removed. Note that changes on
"that were removed": it's the interfaces that were removed, not the array.
Do you have a use-case for interfaces disappearing without the entire object going away? I don't think changes to the list of interfaces are generally part of the de facto D-Bus object model? (dbus-glib and dbus-python certainly can't support it with their current design.)
3048 the given object path. Similarly, the second parameter of the
3049 <literal>InterfacesRemoved</literal> signal contains an array
3050 of the interfaces that was removed. Note that changes on
3051 properties on existing interfaces are not reported using this
3052 interface - an application should use the
s/use/also monitor/ perhaps
3055 <para>
3056 Applications SHOULD NOT export objects that are children of an
3057 object (directly or otherwise) implementing this interface but
3058 which are not returned in the reply from the
3059 <literal>GetAll()</literal> method of this interface on the
it's no longer called GetAll
3070 </programlisting>
3071 </para>
3072 <para>
3073 on respectively the message bus and the remote
3074 application. Whenever a new remote object is created (or an
I tend to think of method calls as being an operation on objects (or proxies), rather than on destinations: "on the message bus, and the remote application's ObjectManager, respectively".
3072 <para>
3073 on respectively the message bus and the remote
3074 application. Whenever a new remote object is created (or an
3075 existing object gains a new interface), the
3076 <literal>InterfacesAdded</literal> signal is emitted and since
emitted, and
3075 existing object gains a new interface), the
3076 <literal>InterfacesAdded</literal> signal is emitted and since
3077 this signal contains all properties for the interfaces, no
3078 calls to the <literal>org.freedesktop.Properties</literal>
3079 interface on the remote object is needed. Additionally, since
are needed
Powered by Splinter

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.