Errors and the introspection format

[Matthew Johnson]

On Fri, 17 Feb 2006, Havoc Pennington wrote:

> On Fri, 2006-02-17 at 10:32 +0000, Matthew Johnson wrote:
>> This came up while I was writing the error support in the Java bindings,
>> if you call a method that returns an error it throws an exception of the
>> type given as the error name. To do this I need to create a class of
>> that type, which I can't do automatically if it isn't in the
>> introspection data. (you can also throw on if you want to return an
>> error from a method implemented on the server).
>>
>> Thoughts?
>
> Some old comments from me on this:
> http://lists.freedesktop.org/archives/dbus/2005-March/002448.html
> http://lists.freedesktop.org/archives/dbus/2005-March/002452.html
> http://lists.freedesktop.org/archives/dbus/2005-March/002460.html
>

I've read over that thread about errors and have a few comments:

(quoting from random parts of the thread)

> Now, this is useful in other scenarios as well. First of all, app
> developers like me can convey to all developers wanting to use hal what
> app level exceptions that hal might throw in the place where they'll be
> looking for it - the introspection data. They don't need to find the
> spec which is likely to be out of date too :-)

This is *exactly* why it should be an annotation. Sure, most languages will
push this onto the programmer not the langaues binding, but even then, I want
to know what exceptions I should be expecting. (for the record I can confirm
that the Hal spec *is* out of date. Of course it doesn't have introspection 
yet either...)

So, Java will expose this in the programming API, and everything else will just
list it as another annotation, this is fine, but the introspection data should
contain all the API, and this includes error conditions.

> > and for Java this might give the following generated client code
> >
> >  package org.freedesktop.Hal
> >
> >  interface Device {
> >    boolean Lock (String reason) throws NoSuchDevice, PermissionDenied,
> >                                        AlreadyLocked, DBusException;
> >  };
> >
> 
> See, this is an ABI that will break if you add/remove exceptions. But
> only Java will break... so will anyone even notice in time?
>

No, it won't break. If you get a new exception thrown it will get thrown via
the DBusException type, if one of those exceptions stops being thrown then...
it just won't get thrown any more. As it happens I have implemented DBusException as a runtime exception so its definition can be ommitted.

Further, how will the breakage be any worse than in:

if (ex.name == "NoSuchDevice") {
     ....
} .... {
} else {
      // default error handling
}

> So, you don't you consider it ABI breakage if the application HAL
> removes / adds exceptions in a supposedly stable ABI? I surely do.

indeed.

In summary---it won't break in java any more than any other language;
and I think it needs specifying somewhere. Most of the bindings have the
ability to specify annotations, why should this be any different. Those
languages which support it can have it as a language feature, those
which don't just have annotations. Generated interfaces looking like:

@annotation("throws", "UnknownDevice")
array getDeviceDetails(string device)

/*
  * this can throw an UnknownDevice error
  */
  array getDeviceDetails(string device)

String[] getDeviceDetails(String device) throws UnknownDevice

are all fine here, but it is something that I feel really ought to be there.

Matt

-- 
Matthew Johnson
http://www.matthew.ath.cx/