[Biojava-l] BioRuntimeException

[Thomas Down]

Hi...

I've just added two new classes, NestedRuntimeException and
BioRuntimeException.  As the names suggest, these are unchecked
exceptions, but they should be used with the same semantics
as their checked equivalents.  Extra subclasses can be added
if necessary, but I'm hoping that use of them won't get too
widespread.  In particular, it would be good if anyone designing
a new interface could consider the possibility that a database-
backed implementation might be written in the future, maybe
fetching data in quite a `lazy' fashion.  In practice, this
probably means that almost any accessor method can potentially
fail, and should be able to signal this using an exception.


Since Java supports three kinds of throwables, and we're now
using all three in BioJava, a quick summary (Matthew: could
you check these?)


Checked exceptions (e.g. BioException):

   These are the standard `day-to-day' exceptions, used
   everywhere.

Unchecked exceptions (e.g. BioRuntimeException):

   In BioJava, these are reserved for the special case of
   `retrofitting' exceptions to an interface which doesn't
   support them (e.g. Sequence).  Probably means that
   the interface is wrong :-(.

   NOTE: Be aware that a few parts of the core Java APIs
   also throw unchecked exceptions -- most notably the collections
   framework.

Errors (e.g. BioError):

   These signal that something has gone badly wrong.
   Sometimes they are generated by the Java virtual
   machine.  In general, you /don't/ want to be catching
   these -- better to allow the whole program to exit.

   In BioJava, we use them to signal an `impossible' condition
   or assertion failure: for instance, the following:


         try {
             Annotation a = new SimpleAnnotation();
             a.setProperty("foo", "bar");
             return a;
         } catch (ChangeVetoException ex) {
             throw new BioError(ex, "Couldn't manipulate annotation");
         }

   Recently, BioErrors have been used in cases where 
   BioRuntimeException is more appropriate, for instance
   the DAS client.  It would be good to get these fixed before
   the 1.2 releases start.


Thomas.