2013-06-21

[Technology] DOMException, its nature and appropriateness for GError reporting

I've had to recently study the nature of the various DOMExceptions specified by the DOM Level 3 Core spec, to better understand whether we want to use the GError reporting system of GLib in GXml, or whether we want to use something else.  I defaulted to using GError, because the spec presents them as exceptions to be raised, and because I was used to handling libgdata errors (which are legitimately run-time errors) with GError.



The GLib Error Reporting documentation is pretty clear about when it's appropriate to use GError: basically, only when it's a run-time issue that a programmer can't reasonably anticipate.


First and foremost: GError should only be used to report recoverable runtime errors, never to report programming errors. If the programmer has screwed up, then you should use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some similar facility. (Incidentally, remember that the g_error() function should only be used for programming errors, it should not be used to print any error reportable via GError.)



Examples of recoverable runtime errors are "file not found" or "failed to parse input." Examples of programming errors are "NULL passed to strcmp()" or "attempted to free the same pointer twice." These two kinds of errors are fundamentally different: runtime errors should be handled or reported to the user, programming errors should be eliminated by fixing the bug in the program. This is why most functions in GLib and GTK+ do not use the GError facility.

Below are my feelings on which DOMExceptions constitute programming errors (and shouldn't use GError) or run-time errors (and should). I look at run-time errors as consequences of the environment in which GXml is used (e.g. is it the fault of a document we're reading in, the content of which we have little control), and programming errors the direct result of a programmed call that's supplying bad data or misusing the document.



I find most of the DOMExceptions to be programming errors.  If you believe that something is more properly a run-time error and deserves GError reporting, please comment and explain why!  I am not an expert.  Like, for invalid characters, GXml might be used by a GUI where a user is entering data, and enters characters that aren't supported.  I think input checking like that should be handled in the application instead of in the GXml library, though; it shouldn't get as far as trying to actually set an attribute with bad data.  Perhaps we could provide convenience validation methods to GXml, though.  Thoughts welcome.







R: Runtime, GError
P: Programming
N: N/A

Defined Constants

N DOMSTRING_SIZE_ERR
If the specified range of text does not fit into a DOMString.
we don't have our own DOMString type, we just use gchar* arrays, which don't really have 
a fixed limit, just as much as you can alloc in a single go.

P HIERARCHY_REQUEST_ERR
If any Node is inserted somewhere it doesn't belong.
this would be a programmer error, like trying to append a node to be a child of itself.

P INDEX_SIZE_ERR
If index or size is negative, or greater than the allowed value.
programmer error, they should check size before accessing non-existent members of lists

P INUSE_ATTRIBUTE_ERR
If an attempt is made to add an attribute that is already in use elsewhere.
programmer error

? INVALID_ACCESS_ERR, introduced in DOM Level 2.
If a parameter or an operation is not supported by the underlying object.
nclear as to when this might happen; property of a document or implementation or the DOM?

?P INVALID_CHARACTER_ERR
If an invalid or illegal character is specified, such as in an XML name.
I'd almost think it's a run-time error, because it probably reflects an issue with the 
document we're working on. Invalid characters are related to the XML version of a document,
and which features our implementation supports. Right now, we basically don't deal with 
this (!). libxml2 has version information, of course, but I'm not sure how it handles 
invalid characters yet. TODO: figure this out.
However, I think of it more as programmer error, because almost all the methods its 
associated with are where the programmer provides a string that might contain it, rather 
than just accessing a string already in the Document. The other ones involve bringing
foreign nodes into documents, and the programmer has the option of checking version 
information and characters beforehand to ensure compatibility
*Document.adoptNode
Document.createAttribute
Document.createElement
Document.createEntityReference
Document.createProcessingInstruction
*Document.importNode
Document.renameNode
Node.prefix.set
Element.setAttribute
DOMImplementation.createDocument
DOMImplementation.createDocumentType

? INVALID_MODIFICATION_ERR, introduced in DOM Level 2.
If an attempt is made to modify the type of the underlying object.
Not really specified for any methods

? INVALID_STATE_ERR, introduced in DOM Level 2.
If an attempt is made to use an object that is not, or is no longer, usable.
Not really specified for any methods

P NAMESPACE_ERR, introduced in DOM Level 2.
If an attempt is made to create or change an object in a way which is incorrect 
with regard to namespaces.
The result of bad input from a programmer, for qualified names.
DOMImplementation.createDocument
DOMImplementation.createDocumentType
DOMImplementation.createAttributeNS
DOMImplementation.createElementNS
DOMImplementation.renameNode
Node.prefix.set

P NOT_FOUND_ERR
If an attempt is made to reference a Node in a context where it does not exist.
Programmer error, they're specifying the node in reference, so like with insertBefore, 
removeChild, etc.

?RP NOT_SUPPORTED_ERR
If the implementation does not support the requested type of object or operation.
We couldn't don't deal with the features of our implementation or XML versions (that's bad, 
but oh well); not exactly sure where this would fall. Sometimes it seems like it would be 
a programming error (trying to adopt a Document node into another Document with adoptNode) 
but other times, like when creating a document, I could see that being a runtime error.

? NO_DATA_ALLOWED_ERR
If data is specified for a Node which does not support data.
Currently nothing raised it according to the spec, and there aren't any obvious cases 
where I want to.

?PR NO_MODIFICATION_ALLOWED_ERR
If an attempt is made to modify an object where modifications are not allowed.
We currently don't have a concept of a read only node, and thus no way to check. I'm not
sure if libxml2 has a concept of readability either. Its common for most nodes to want to 
raise this, so perhaps it's a real use case we should support, but even then, it feels like
 something that isn't variable at run time, and that a programmer might be able to reasonably 
anticipate and check for.

P SYNTAX_ERR, introduced in DOM Level 2.
If an invalid or illegal string is specified.
Probably a programmer error, if they're the ones specifying strings.

P TYPE_MISMATCH_ERR, introduced in DOM Level 3.
If the type of an object is incompatible with the expected type of the parameter 
associated to the object.
Only used by DOMConfiguration.setParameter, which we don't support. This seems like a 
programmer thing, anyway
DOMConfiguration.setParameter

P VALIDATION_ERR, introduced in DOM Level 3.
If a call to a method such as insertBefore or removeChild would make the Node invalid 
with respect to "partial validity", this exception would be raised and the operation 
would not be done. This code is used in [DOM Level 3 Validation]. Refer to this 
specification for further information.

P WRONG_DOCUMENT_ERR
If a Node is used in a different document than the one that created it (that doesn't 
support it).
Definitely a programmer error.

Keine Kommentare:

Kommentar veröffentlichen

Dieses Blog durchsuchen

Labels

#Technology #GNOME gnome gxml fedora bugs linux vala google #General firefox security gsoc GUADEC android bug xml fedora 18 javascript libxml2 programming web blogger encryption fedora 17 gdom git emacs libgdata memory mozilla open source serialisation upgrade web development API Spain containers design evolution fedora 16 fedora 20 fedora 22 fedup file systems friends future glib gnome shell internet luks music performance phone photos php podman preupgrade tablet testing typescript yum #Microblog Network Manager adb apache art automation bash brno catastrophe css data loss debian debugging deja-dup disaster docker emusic errors ext4 facebook fedora 19 gee gir gitlab gitorious gmail gobject google talk google+ html libxml mail microsoft mtp mysql namespaces nautilus nextcloud owncloud picasaweb pitivi ptp python raspberry pi resizing rpm school selinux signal sms speech dispatcher systemd technology texting time management uoguelph usability video web design youtube #Tech Air Canada C Electron Element Empathy Europe GError GNOME 3 GNOME Files Go Google Play Music Grimes IRC Mac OS X Mario Kart Memento Nintendo Nintendo Switch PEAP Selenium Splatoon UI VPN Xiki accessibility advertising ai albums anaconda anonymity apple ask asus eee top automake autonomous automobiles b43 backup battery berlin bit rot broadcom browsers browsing canada canadian english cars chrome clarity comments communication compiler complaints computer computers configuration console constructive criticism cron cropping customisation dataloss dconf debug symbols design patterns desktop summit development discoverability distribution diy dnf documentation drm duplicity e-mail efficiency email english environment estate experimenting ext3 fedora 11 festival file formats firejail flac flatpak forgottotagit freedom friendship fuse galaxy nexus galton gay rights gdb german germany gimp gio gjs gnome software gnome-control-center google assistant google calendar google chrome google hangouts google reader gqe graphviz growth gtest gtg gtk gvfs gvfs metadata hard drive hard drives hardware help hp humour ide identity instagram installation instant messaging integration intel interactivity introspection jabber java java 13 jobs kernel keyboard language language servers languages law learning lenovo letsencrypt libreoffice librpm life livecd liveusb login lsp macbook maintainership mariadb mario matrix memory leaks messaging mounting mouse netflix new zealand node nodelist numix obama oci ogg oggenc oh the humanity open open standards openoffice optimisation org-mode organisation package management packagekit paint shedding parallelism pdo perl pipelight privacy productivity progress progressive web apps pumpkin pwa pyright quality recursion redhat refactoring repairs report rhythmbox sandboxes scheduling screenshots self-navigating car shell sleep smartphones software software engineering speed sql ssd synergy tabs test tests themes thesis tracker travel triumf turtles tv tweak twist typing university update usb user experience valadoc video editing volunteering vpnc waf warm wayland weather web apps website wifi wiki wireless wishes work xinput xmpp xorg xpath
Powered by Blogger.