0

I was going through the java source code for LocalDate API, and found that the methods are missing throws declaration. However the javadoc clearly mentions that the method could throws DateTimeException. Below is the source from LocalDate API from Java 8 .

/**
 * Formats this date using the specified formatter.
 * <p>
 * This date will be passed to the formatter to produce a string.
 *
 * @param formatter  the formatter to use, not null
 * @return the formatted date string, not null
 * @throws DateTimeException if an error occurs during printing
 */
@Override  // override for Javadoc and performance
public String format(DateTimeFormatter formatter) {
    Objects.requireNonNull(formatter, "formatter");
    return formatter.format(this);
}
  1. Should this be the right way to declare a method which throws exception (I expected throws in method signature which enables the clients to properly handle the exception, but this does not give the client a clue about exception unless the javadoc is being read) ?

Please me know if I missed something to understand this properly?

technoJ
  • 175
  • 1
  • 1
  • 16
  • `DateTimeException` is a `RuntimeException`, need not be thrown. Always prefer unchecked exception, so that you handle it only when required – sidgate Oct 23 '18 at 05:18
  • For unchecked exceptions it’s considered good style not to declare them in the `throws` clause but to document them in the Javadoc/API documentation. – Ole V.V. Oct 23 '18 at 06:23

1 Answers1

0

DateTimeException is an unchecked exception, so it doesn't have to be declared methods.

Why does LocalDate#format declare it? Because it can be thrown by methods it itself delegates that execution to. Following the call chain, we see that DateTimeFormatter.formatTo(TemporalAccessor, Appendable) is the method doing the actual work, and it is throwing the exception; and none of the intermediate methods is catching/handling it.

public void formatTo(TemporalAccessor temporal, Appendable appendable) {
    ...
    try {
        ...
    } catch (IOException ex) {
        throw new DateTimeException(ex.getMessage(), ex);
    }
}

I believe this is indeed an example of good exception documentation (document exceptions that should be expected, be they checked or not, even if you are not explicitly throwing them in the method in question)

ernest_k
  • 44,416
  • 5
  • 53
  • 99
  • Good documentation, sure. But terrible design decision by the developers who wrote this code. I'm writing an API that excepts among other things, dates in String format (json). Naturally I want to give an informative error response if the caller provides an invalid date (for example, stating exactly which field it was) instead of an ugly generic 500 error. That leaves me no choice but to catch this runtime exception. – j5423951 Mar 29 '22 at 08:31
  • @j5423951 I think what you're saying there describes expected responsibilities. You indeed should handle exceptions if you want to customize your response. If you don't do that, the only thing that can be said is that ***your** code crashed*. The date time API has no role to play in that. If you're talking about automatic JSON binding errors happening when inbound API requests are being parsed, then that's a problem of the API framework, still not a bad design in the date time API. But I think you can customize your validation to add the desired message when parsing fails. – ernest_k Mar 29 '22 at 12:29
  • One should not have to catch RuntimeException at all, unless in code that deals with threads/requests (ie one thread/request dying should not kill the whole server) etc. Throwing RuntimeException for simple date parsing errors is absurd. It is not reasonable for them to expect me to validate the String before the parsing, but I still want to handle any error that occured when it tried to parse the String. – j5423951 Mar 30 '22 at 14:21
  • That's an interesting point of view, @j5423951. I think on the contrary that being *forced* to handle that parsing errors would be annoying, just because someone made it a checked exception. But again, if it's a runtime exception with the "not having to handle it" assumption behind it, then that only leaves the system to crash. I think we're having too many conversations in one. – ernest_k Mar 30 '22 at 14:26
  • Most developers don't want their systems to crash on a faulty date string that they are not able to verify first in a reasonable and bulletproof way. So "leaving the system to crash" is not an option. So, it has to be catched somewhere, anyway. And I'm of the view that systems should not crash "bigger" than necesarry. Most custom software has (or should have) well defined ways to return an apropriate error to the calling system, and and a generic 500-error (if a web based API or a regular website) is not apropriate except for bugs in your system. Faulty input should result in apropriate error. – j5423951 Mar 31 '22 at 16:01