error classes

In our previous discussions of error handling, I think that we agreed that we would use exceptions for errors that were immediately detectable (argument type mismatches and the like).  Someone (Adam?) said that the IDL will create some of these for us automatically.  If that's the case, it would be great if he could send an explanation/link around so that we can understand exactly what we get for free.

There is an ongoing discussion of how to handle the gUM success and failure callbacks. This is a case where the code requests an operation and knows that at some point it will get notification of either success or failure.    There is also another kind of error, namely those that occur later in processing, for example network problems when using PeerConnection or running out of memory while recording.  There is no corresponding success event to go with these.  Instead they represent problems that can come up at any point during processing.

Both the success and failure callbacks and the runtime errors define error classes containing information about the error.  Currently each spec defines its own classes, and there's a lot of rather unsystematic overlap in these definitions, and I think it's time to start cleaning it up.


1.       The gUM spec has NavigatorUserMediaError with attributes name, message, and constraintName

2.       The recording spec has RecordingError with attributes name and message

3.       The webRTC  spec has RTCError with attributes name and message, along with RTCSDPError which adds sdpLineNumber.

4.       The image capture spec has PhotoErrorEvent with attribute photoError (which may be equivalent to 'name' in the other specs.)

5.       The image capture spec also has SettingsErrorEvent with attribute PhotoSettings (which looks a bit like constraintName in the guM spec.)

The errors in the image capture spec inherit from event, but none of the other errors inherit from any class.

It seems like we all want an error class with name and message attributes. There is a DOMError class defined at http://dom.spec.whatwg.org/#errors which has a name attribute, but we would need to extend it to hold 'message' as well.  DOMError comes with a table listing the legal values for name, but it can be extended.  Some of the  names that are already defined could be used as is, such as 'NetworkError' or 'TimeoutError'.

So the first question is:  should each spec extend DOMError separately or should we define the base error class in the gUM spec and let the other specs inherit it?  If we do put something in the gUM spec,  it would have to have a generic name like 'MediaError', since a lot of the errors it would be used for are not tied to gUM.   On the whole, I think inheriting would be cleaner.  Each spec would have to define the new values for 'name' that it required, but wouldn't need the extra class definition.   (Each spec should probably also explain which of the existing DOMError names it would use, so that programmers know the full range of error names that the API might use.)

If we do choose to inherit/extend, it would make sense to define some sort of ConstraintError (which would have a 'constraintName' attribute) in conjunction with the Constrainable interface so that other specs would reuse both.   If Constrainable gets extended to handle settings as well (or if a separate Settings interface is defined), SettingsError would follow the same pattern.

Another question involves the details of how the error handler works.  In our current specs, the error object is passed directly to  the onerror event handler.  A while back Travis sent around a proposal for a slightly different model.  http://lists.w3.org/Archives/Public/public-media-capture/2012Dec/0167.html  In this model, the error object is an _attribute_ of the class (e.g. MediaRecorder).   The UA sets this attribute to an appropriate value when an error occurs and then calls the onerror handler, which then looks at the attribute to get the error information.    I'm not sure how important this distinction is, but we have to decide which model to use (and all four specs should use the same model.)


-          Jim