Errors and the introspection format

[Havoc Pennington]

Hi,

On Sat, 2006-02-18 at 10:44 +0000, Matthew Johnson wrote:
> DBus has a great self-documenting system for the APIs, if you include
> exceptions and possibly a short description, it would be *really*
> *really* good, and contain everything I can think that I would like to
> know. With the aid of the XSLT I posted to the list a couple of days ago
> you can even generate nice javadoc-like webpages from it.

Including exceptions in the docs (like javadoc @throws) I have no
problem with. What I think is a mistake (for dbus) is putting them in
the method signature and using them to generate per-method code. That
creates a whole school of issues and "ABI breaks" that only one binding
can have, and changes how you do API design (e.g. I think the HAL Lock()
API from the old thread is kind of a bad pattern in
non-checked-exception languages, I might go with return codes or
something instead)

I think it might be fine to have some kind of global list of exceptions,
and generate the exception classes in Java. Then you can write nice
try/catch code. I just don't think you should generate the throws
clauses on methods. For a global list of exceptions, the main question
would be where in the introspection data to put them though.

I thought you said you were making DBusException unchecked anyway? It's
certainly not typical to have throws clauses for unchecked exceptions,
only javadoc @throws at most.

>  and I do believe
> that it will benefit all programmers of clients due to having them
> written down at the top of the function.

You're saying it would be good _if_ the information was up-to-date and
accurate. Let's concede that for a moment.

I'm saying it won't be, because only Java programmers will care. If I'm
writing a dbus object in Python, I'm not going to get the exception info
right. Also, having checked exceptions vs. not changes how you want to
do API design.

The "DBusException" approach is the norm in Java server-side programming
at least anyway; EJBException, JMSException, HibernateException,
SQLException, people always just have one generic exception for the
whole module. It's not like this is some kind of Java heresy.

But again we can do one better, you could define classes for a bunch of
DBusException subclasses (including at least the standard exceptions,
and if we can think of a way then also module-specific ones).

I would probably do DBusException, and then group a couple categories of
the standard exceptions with base classes, like:

class DBusException extends RuntimeException;
class DBusCommunicationException extends DBusException;
class DBusIOError extends DBusCommunicationException;
class DBusNoNetwork extends DBusCommunicationException;

etc.

Just because it seems useful to lump together all kinds of
"communication exception" and handle those. I'd probably also convert
the dbus NO_MEMORY error into the standard Java OutOfMemoryException or
whatever it's called since a generic OOM handler is probably correct for
handling dbus OOM as well.

Havoc