Design and distinction of types of Jackson exceptions.

[garretwilson]

This is somewhat in the context of #4165 , for which I soon intend to circle back and help document the API. But I wanted to ask everyone and especially @cowtowncoder some questions about the distinction of Jackson exception types.

In my own core Java library (which has been evolving for over two decades), I'm releasing a version that cleans up a lot of legacy things. Over the years I realized that I've accumulated various "data exception" classes. Some of them are checked. Some of them are unchecked. Some of them descend from IOException and some of them don't. Some of them have to do with parsing. Some of them have to do with "syntax" (how that is different from parsing I'm not completely sure). They all seemed like a good idea at the time! 😅

So I took a step back and tried to reason from first principles what a "data exception" means, and how it is different from a general "I/O exception". For example, if I try to read a JPEG file and it turns out to be corrupt, is that an error with I/O or an error with the data? I think it can be considered a type of IOException. But as you go up the processing layers, it gets murkier whether we are still dealing with "I/O" as such. (You can read all my ponderings about this at JAVA-350, but it's not required reading and maybe not even recommended. hehe)

Anyway the concept I seem to be converging on is that, at a certain level, converting the data read from the file to some other type of data is a distinct process from I/O processing, and should result in an exception that is not an IOException. This is because, conceptually, I could read in an entire XML file (as an example) and store it in a DOM tree, and it will be sitting in memory. Then if I tried to convert the DOM tree to some object via a mapping function, the data conversion error thrown shouldn't be an IOException, because no I/O at all was being performed! This is no different than converting a string to something else: I don't suppose anyone would expect Integer.parseInt(String) to throw an IOException; similarly, convertXmlToFooBar(Node) probably shouldn't throw an IOException either.

Following this, just because some deserialize(…) method both 1) reads an XML file and 2) maps the DOM to an object in the same method, doesn't to me seem like the mapping suddenly results in an IOException—it would seem there should still be some distinct exception for data conversion problems. (Or does the fact that the data conversion happens in the same method mean that the data conversion exceptions should be converted to some form of IOException?)

So I dove into Jackson to see if it aligned with the conceptualization I was forming, and I found that DatabindException is used for "all databind level processing problems, as distinct from stream-level problems or I/O issues below". But interestingly, DatabindException actually ultimately descends from IOException!

The implication of this is that methods such as ObjectMapper.treeToValue(TreeNode n, Class<T> valueType) (which I think is similar to my examples above of Integer.parseInt(String) and convertXmlToFooBar(Node)), in throwing a JsonProcessingException, are throwing a type of IOException even though in my mind ObjectMapper.treeToValue(TreeNode n, Class<T> valueType) involves no I/O at all. (Maybe it treats a string as an InputStream internally to reparse something, but to me that doesn't make the method perform I/O as we usually mean.)

So @cowtowncoder , I'm curious—did you have a similar quandary about whether to make JsonProcessingException and (more to the point) DatabindException descend from IOException or be a completely separate hierarchy of data conversion exceptions? Looking back would you have done it differently? (I'm just curious, and the discussion will help me with decisions I'm making with my libraries.)

[cowtowncoder]

Ok, so somewhat condensed answer to much more nuanced question: originally use of IOException as the base type was for convenience: before multi-type-catch, it was easier for caller to only catch (or declare) general IOException, if all Jackson exception extended that. This because almost all read/write methods would expose IOException anyway.
It does have downside of also exposing IOException in places where no I/O does occur, as you point out; most notably with conversion methods but overall it seems like a relatively minor issue.

But I have since changed my mind about this, partly due exceptions being difficult to handle with Java 8 streams, and similar processing.
Because of this, Jackson 3.0 (master) uses RuntimeException as the base exception type for Jackson exceptions.

Now: exception in Jackson 2.x are bit redundant since new types I added for 3.0 -- StreamReadException (for jackson-core read side), StreamWriteException (jackson-core write side) and DatabindException (jackson-databind) -- were also backported in 2.x to possibly help with eventual migration.
They are paired so that:

• JacksonException is meant as replacement for JsonProcessingException
• StreamReadException replacement for JsonParseException
• StreamWriteException replacement for JsonGenerationException
• DatabindException replacement for JsonMappingException (json-databind)

but since "old" exception cannot be removed during 2.x, this means there are 3 "extra" exception types in hierarchy.
My intent is to at least start converting unit tests to use newer types for verification. Whether this makes sense for users I dont know: it is hard to know before one tries to migrate Jackson 2.x based code for Jackson 3.0.

Still, eventually renaming should improve readability: exceptions are not JSON-specific, for one, and JacksonException is bit more accurate than JsonProcessingException.

So, yes, I think that in hindsight it would have made more sense to not base exceptions on IOException.

Whether parallel hierarchy is useful is actually an interesting question: Jackson 3.0 does actually wrap IOException as WrappedIOException, which is a sub-class of JacksonException.
However, it is not a subtype of any other jackson-provided exception.

I hope this helps untangle some aspects of Jackson design.

[garretwilson]

Thank you for taking the time for an in-depth reply.

… due [to] exceptions being difficult to handle with Java 8 streams, and similar processing …
… Jackson 3.0 (master) uses RuntimeException as the base exception type for Jackson exceptions.

Working with checked exceptions in streams, Optional, and the like is certainly an issue, and your decision is reasonable. But I recognize that IOException will probably still be around in supporting code even if I were to try to remove it from my library; and moreover it still is the conventional way to indicate I/O problems. So for me I've decided to stay with IOException but in my applications use libraries such as Faux Pas which use "sneaky throws" to hide the exceptions from the compiler when performing e.g. stream operations. (This is something that junior coders should be trained in before using, though, because it's something easy to misuse, and should be applied surgically.)

… new types I added for 3.0 …

The new JSON-agnostic exception types are definitely a positive step.

Jackson 3.0 does actually wrap IOException as WrappedIOException, which is a sub-class of JacksonException.

(Note that there is also com.fasterxml.jackson.datatype.jdk8.WrappedIOException, which is not a subclass of JacksonException.)

I would encourage you to name that class JacksonIOException or some other name that better reflects its purpose (wrapping an IOException in order to make it a JacksonException). Otherwise the name is so general it doesn't convey what it does, and is easy to get confused with e.g. java.io.UncheckedIOException.

I hope this helps untangle some aspects of Jackson design.

Yes, fantastic, thanks.

For my core library I think what I'm going to have a single non-I/O DataTransformException which will serve as a basis for data transformation problems (such as data mapping—conceptually a super-class of DatabindException). Lower-level syntax issues will be handled by ParseIOException, which of course is an IOException. Once I restart PLOOP, its conversion errors may be subclasses of DataTransformException.

If you think about the traditional ETL sequence, that parallels Jackson's new StreamReadException/DatabindException/StreamWriteException; or in my case ParseIOException/DataTransformException/IOException, in which the first and last are I/O operations, but in which the "transform" stage doesn't necessarily involve I/O. And if transformations are ever integrated into some larger I/O operation, of course DataTransformException can be wrapped in an IOException.

That's not perfect, but as you and I both know, there's really no perfect answer in this area and the goal is to keep massaging it and making it more consistent and reasonable over time.

Thanks for helping me think about this!

[cowtowncoder]

I would encourage you to name that class JacksonIOException or some other name that better reflects its purpose (wrapping an IOException in order to make it a JacksonException). Otherwise the name is so general it doesn't convey what it does, and is easy > to get confused with e.g. java.io.UncheckedIOException.

Yes, this makes sense. Also good point wrt WrappedIOException from Java8 datatype module. Not quite sure how to go about that one, due to backwards-compatibility; although in Jackson 3.0 it has been merged into main databind and no longer problematic.

[cowtowncoder]

Name changed to JacksonIOException as suggested, for 3.0.