first cut of hal service description file

[Havoc Pennington]

On Thu, 2005-03-31 at 20:13 -0500, David Zeuthen wrote:
> Well, given that the design goals of D-BUS is intra-desktop-session-
> IPC
> and system-desktop-IPC we don't really want too many different API's
> which means we'll have a limited set of applications providing D-BUS
> services. 

This isn't obvious to me; KDE has quite a lot of DCOP services. But this
is the kind of thing we can confirm post-1.0 when we see how real life
evolves.

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

IIRC part of the reason C# doesn't typecheck "throws" is that they
didn't think they could get it right for C++/COM components. This is the
same thing. If we were only dealing with Java, it would be OK. But if
you mix in languages without this in the type system, you have to either
munge in the exception stuff via gross hacks to languages without it:

  connection.addExceptionToObject(o, "MyMethod", "WhateverException");

Or you have to make Java deal with it:

 boolean Lock (String reason) throws DBusException;

Note that we made the _opposite_ decision for static typing in general,
where we make Python and Perl do the equivalent of
addExceptionToObject() - they have to specify the method signatures
somehow which is gross.

In that case we're basically chasing the majority case, and I think we
are here too.

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

You can just use comments for this, though.

> Second, which is more blue sky (but we should aim high), you can build
> this into IDE's, e.g. MonoDevelop, Eclipse or whatever could hint the
> app developer that she should handle these exceptions.

I don't deny that it would be somewhat useful for Java developers, but
here is my argument:

 - if C/C++/Perl/Python/C# all work this way, it really can't be a
   fatal flaw - those languages seem fine
 - fewer features is inherently simpler
 - we know this feature introduces risk that:
    - programmers will get it wrong
    - it will cause inter-language semantic mismatch and ABI issues
 - this feature can be added compatibly later if we find 
   out we really screwed up

So, it just doesn't feel like a 1.0 feature to me.

Havoc