jackson-databind
jackson-databind copied to clipboard
FasterXML
Clarify which `IOException` types `ObjectReader` methods might throw.
Documentation Improvement
It would be helpful to improve the API documentation and/or method signatures for ObjectReader to indicate specifically which categories of exceptions are thrown.
If I look at the API documentation for e.g. ObjectWriter.writeValue(OutputStream out, Object value) throws IOException, StreamWriteException, DatabindException, I know exactly what I'm getting into: in addition to the traditional IOException, I must check for StreamWriteException and DatabindException.
Granted these are only documented because they are checked exceptions; in a perfect world they would be documented in the method Javadocs as well. But they are there in the signature at least.
So what about when it comes time to deserialize something? For ObjectReader.readValue(InputStream src) throws IOException, the signature only mentions that it throws IOException. It turns out that StreamWriteException and DatabindException extend from JacksonException, which itself is an IOException. So really ObjectWriter.writeValue(OutputStream out, Object value) could have obscured things further by simply saying only that it returned IOException, as ObjectReader does. 😬
But instead I suggest it would be better if ObjectReader.readValue(InputStream src) were more detailed in indicating which exceptions it will throw; in my case, I have reasons to distinguish among StreamWriteException, DatabindException, and other IOExceptions.
