Proposing ObjectManager interface

[David Zeuthen]

Hey,

On Mon, Feb 28, 2011 at 10:52 AM, Simon McVittie
<simon.mcvittie at collabora.co.uk> wrote:
> On Mon, 28 Feb 2011 at 10:24:16 -0500, David Zeuthen wrote:
>> 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).
>
> I for one had never heard of such guidance!
>
> I think Telepathy is a lot more property-happy than your APIs - we use
> properties for most things that we expect to be either immutable, or reliably
> change-notified. We mostly use getter methods for things that need to be
> polled, and name them RequestXyz(), where Request means "don't return until
> you've asked the server and it has replied".
>
> We could really do with an appendix to the D-Bus Specification, or a parallel
> document, or something, that describes the interoperable high-level object
> model. I get the impression that dbus-glib, GDBus, dbus-python, QtDBus etc.
> agree on almost everything, but disagree on a few details; if nothing else,
> it'd be good to document an interoperable subset that every competent binding
> should be able to implement.
>
> (For instance, overloading by argument type is controversial enough not to be
> in the interoperable subset; properties that aren't C identifiers are annoying
> for QtDBus, so I think the interoperable subset should recommend the same
> naming restrictions as member names, with CapitalizedWords recommended; and
> so on.)

Yeah, totally could use a "Best Practices" document... more for app
writers, not so much to guide bindings authors ... after all, a
particular D-Bus binding should not really encode any policy; then
again, it usually ends up doing by encouraging a certain style just
because some API in the binding is easier to use than others. For
example, gdbus-codegen [1] totally encourages property-happy APIs for
better or worse.

Other things we should cover includes versioning - these days I mostly
use these guidelines
http://0pointer.de/blog/projects/versioning-dbus.html

With good versioning available (and support for it in tools e.g.
easily supporting AppInterface1 and AppInterface2 simultaneously),
it's relatively cheap to provide parallel installable D-Bus services
which makes it relatively "cheap" to do rewrites where you can fix ABI
mistakes in previous versions. Personally I think we should encourage
this - people shouldn't be afraid to rev interfaces (this is a heated
political discussion, though).

Should also cover whether adding parameters to methods/signals is an
ABI break (it's not in C, for example) - I'd argue it's not but most
my code would probably fail if this happened. Also breaks C++ where
Class::method(param) and Class::method(param, param) is allowed.
Either way, guidance is needed here, I think.

>> >>   This
>> >>   signal contains all properties for the added interfaces.
>> >
>> > Mutable or immutable properties?
>> [...]
>> 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"....
>
> OK, sounds like "all the properties".

I think so, yeah.

     David

[1] : http://people.freedesktop.org/~david/gdbus-binding-tool-20100902/gdbus-codegen.html