RFC: Annotations for object path data type

[Daniel P. Berrange]

A pattern I've have used in several DBus applications now, involves
a root 'manager' object which has methods for retrieving, creating &
deleting child objects. The retrieve method would return an array
of object paths, the create method would return an object path, and
the delete method would accept an object path. The object paths
passed around could conceivably we fully qualified wrt to the service,
or they might be relative to the manager object's path, or they might
be paths pointing to objects provided by another service on the bus.

As a concreate example:

 - A well known client (service) name  'org.autobuild.Angel'

 - A root object '/org/autobuild/angel'  with methods

      array object_path  list_builders()

      object_path create_builder(name: string)

      delete_builder(builder: object_path)

 - Build child objects under '/org/autobuild/angel/builder/<NAME>'

Now all the DBus spec says about the object path data type is that the
content must be a valid object path. Specifically, it does not say that
the object path has to refer to an object in the same service, nor does
it say that the object path has to be fully qualified. 

This is fine in itself, but it does place a limit on what client bindings 
can do when (un)marshalling data of type 'object path'. For example,
take the 'create_builder' method above - a client binding cannot assume
that the object path returned is scoped to the 'org.autobuild.Angel'
well known client, nor whether it is a fully qualified, or relative path.

So, as an example, if I were creating a new builder with the Perl bindings,
the code would go something like:

   # Get a handle to the manager object
   my $angel = $bus->get_object("org.autobuild.Angel", "/org/autobuild/angel");

   # Create a new builder called 'Foo'
   my $builderPath = $angel->create_builder("Foo")

   # $builderPath contains a relative object path '/builder/foo'

   # Now get a handle to the newly created builder object
   my $builder = $bus->get_object("org.autobuild.Angel", "/org/autobuild/angel" . $builderPath);

   ... do some stuff with the builder object ...
   
   # Lets delete it now
   $angel->delete_builder($builderPath)

Now, you might think this is not too bad, but if the client bindings were
able to know that the '$builderPath' return by the 'create_builder' method
was a relative to the object path of the object on which the method was
invoked, then it could return a handle to that object directly. Similarly,
in the 'delete_builder' method, the bindings would be able to automatically
take a builder object & marshall its underlying object path appropriately.
So the code might now look like:

   # Get a handle to the manager object
   my $angel = $bus->get_object("org.autobuild.Angel", "/org/autobuild/angel");

   # Create a new builder called 'Foo'
   my $builder = $angel->create_builder("Foo")

   ... do some stuff with the builder object ...

   $angel->delete_builder($builder)

This kind of little difference would make using client bindings much
nicer - largely hiding the concept of object paths from the programmer.

So, now to the main point of this mail - how can the developer of the
service, provide the neccessary information to client bindings about
the context of the object paths, to let them reliably do the marshalling
between object paths & actual remote object handles. Two possibilities:

 a) Create some new data types with specific meanings, which can be
    used in place of 'object path'. For example 'root object', and
    'child object'

 b) Define an annotation for the 'object path' data type, eg

     Name:  org.freedesktop.DBus.DataType.ObjectPath.Scope
     Value: 'rootObject' or 'childObject'

I'm not really serious about option a) - i just mention it for sake of
completeness - option b) is definitely my preferred choice. I could just
go ahead & implement this in the Perl bindings, which would satisfy my
own immediate needs, however, I think it would be of much greater value 
if all the language bindings supported this as an 'officially blessed' 
annotation for the object path data type. 

So, vote now for the annotation: yay / nay !

If it gets a yay, I'll create a patch for the spec detailing this
annotation.

Regards,
Dan.
-- 
|=-            GPG key: http://www.berrange.com/~dan/gpgkey.txt       -=|
|=-       Perl modules: http://search.cpan.org/~danberr/              -=|
|=-           Projects: http://freshmeat.net/~danielpb/               -=|
|=-   berrange at redhat.com  -  Daniel Berrange  -  dan at berrange.com    -=|
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.freedesktop.org/archives/dbus/attachments/20060114/9b148e30/attachment.pgp