Typos and small content issues in the Exceptions tutorial ( https://dev.java/learn/exceptions/ )

[willy-b]

Hello dev.java team!

Reporting a few typos and possible small content issues on the Exceptions tutorial ( https://dev.java/learn/exceptions/ ) in case the team is interested to fix them.

---

In the latest version of https://dev.java/learn/exceptions/what-is-an-exception/ (archived as is at https://web.archive.org/web/20260504040350/https://dev.java/learn/exceptions/what-is-an-exception/ )

• "occurred" is accidentally spelled "occured" twice in the two diagrams:

1. (1st image below)

and 2) (see 2nd image)

The differently styled original form of these diagrams from the original tutorial page which this part of this page is derived from did not have this typo, see https://docs.oracle.com/javase/tutorial/essential/exceptions/definition.html (archived as is at: https://web.archive.org/web/20260504041615/https://docs.oracle.com/javase/tutorial/essential/exceptions/definition.html ).

• In the sentence

  The method must provide a throws clause that lists the exception, as described in Specifying the Exceptions Thrown by a Method.

  "Specifying the Exceptions Thrown by a Method" should probably be hyperlinked (it was on the original tutorial this section is derived from, compare with https://docs.oracle.com/javase/tutorial/essential/exceptions/catchOrDeclare.html , archived as is at: https://web.archive.org/web/20260504042451/https://docs.oracle.com/javase/tutorial/essential/exceptions/catchOrDeclare.html ).

• In the sentence

  The section Unchecked Exceptions — The Controversy talks about when it is appropriate to use unchecked exceptions.

  "Unchecked Exceptions — The Controversy" should probably be hyperlinked to the appropriate section, as it was in the original form of the tutorial this part of this page was derived from ( https://docs.oracle.com/javase/tutorial/essential/exceptions/catchOrDeclare.html , archived as is at: https://web.archive.org/web/20260504042451/https://docs.oracle.com/javase/tutorial/essential/exceptions/catchOrDeclare.html ).

---

In the latest version of https://dev.java/learn/exceptions/catching-handling/ (archived as is at https://web.archive.org/web/20260504172747/https://dev.java/learn/exceptions/catching-handling/ )

• In the two sentences

  The argument type, ExceptionType, declares the type of exception that the handler can handle and must be the name of a class that inherits from the Throwable class. The handler can refer to the exception with name.

  [bold added to focus on text of concern]

  "can refer to the exception with name" seems malformed from being copied incorrectly from the original tutorial this page was derived from ( https://docs.oracle.com/javase/tutorial/essential/exceptions/catch.html , archived as is at https://web.archive.org/web/20260504045145/https://docs.oracle.com/javase/tutorial/essential/exceptions/catch.html ). In the original article the previous code snippet had an italicized placeholder "name" after each ExceptionType , and that is what is referred to here, but the code snippet no longer features that and has particular variable names for each exception handler on this page (e.g. the dev.java version has a 2nd version of the code snippet on the original page which uses "FileNotFoundException fnfe" instead of "FileNotFoundException name" right above this sentence).

• In the sentence

  They can do error recovery, prompt the user to make a decision, or propagate the error up to a higher-level handler using chained exceptions, as described in the Chained Exceptions section.

  it would be helpful for "Chained Exceptions section" to be a hyperlink as it was in the original tutorial this page is derived from ( https://docs.oracle.com/javase/tutorial/essential/exceptions/catch.html , archived as is at https://web.archive.org/web/20260504045145/https://docs.oracle.com/javase/tutorial/essential/exceptions/catch.html ).

• Constraints on the exceptions caught in a multi-catch are described "same" as the constraints on exceptions caught in multiple catch blocks, which is potentially misleading:

  Note also that the compiler puts the same constraints on the exceptions you catch with this [multi-catch] syntax as the ones it puts on catching several exceptions with several catch blocks [not quite, order matters for multiple catch blocks (caught exceptions need not be disjoint, but subclasses cannot precede superclasses in multiple catch blocks), but not for multi-catch]. Namely, these exceptions cannot extend one another, in any other order [ for multi-catch, some orders allowed for multiple catch blocks]. Thus, the following code does not compile, with a Types in multi-catch must be disjoint error message [message is: "Alternatives in a multi-catch statement cannot be related by subclassing" but internal error identifier is compiler.err.multicatch.types.must.be.disjoint (ref: https://github.com/openjdk/jdk21/blob/890adb6410dab4606a4f26a942aed02fb2f55387/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties#L632 )].

  The constraint described is not the same constraint as what multiple separate catch blocks for the same try have. The order matters when using multiple separate catch blocks in that all catch blocks must be reachable -- a catch block cannot catch a subtype of an exception caught in an earlier catch block as it would never be reachable. It is true that a valid multi-catch is semantically equivalent to a series of separate catch blocks with the same body, where the catch blocks are generated in order, one for each type in the multi catch. But the multi-catch constraint does not depend on order (caught types must be disjoint in multi-catch which is stricter than separate catch blocks) and so the above description is incorrect.

  To see this, compare a valid scenario with multiple catch blocks, where there is a catch for ArithmeticException followed by a catch for the superclass Exception, which is allowed as long as the subclass comes before the superclass:

  try {
    int a = 1;
    int b = 0;
    int c = a/b;
  //}catch (Exception e) { // not allowed to precede ArithmeticException, should fail to compile
  //    IO.println("General exception: " + e);
   } 
  catch (ArithmeticException e) {
    IO.println("ArithmeticException: " + e);
  } catch (Exception e) { 
    IO.println("General exception: " + e); // ok after ArithmeticException, not before
  }
  

  with an invalid attempted multi-catch for ArithmeticException and Exception which fails in any order:

  try {
    int a = 1;
    int b = 0;
    int c = a/b;
  } // constraint on multi-catch not quite equivalent to constraint on multiple catch blocks
    // order matters for multiple catch blocks (subclasses can come before, but not after) but NOT for multi-catch
  catch (ArithmeticException | Exception e) {
    IO.println("Exception: " + e);
   }
  

  

• In the sentence

  This example uses output classes defined in java.io, which are covered in the Basic I/O section.

  "the Basic I/O section" should be hyperlinked (as it was in the original tutorial this content was copied from, see https://docs.oracle.com/javase/tutorial/essential/exceptions/handling.html , archived at https://web.archive.org/web/20260504183333/https://docs.oracle.com/javase/tutorial/essential/exceptions/handling.html ).

• In the sentence

  The try-with-resources Statement section has more information.

  "try-with-resources Statement section" might as well be hyper-linked though it is within the same article and easy to find, for consistency with other intra-page links like "Suppressed Exceptions".

• In the sentence

  These variable still need to implement java.lang.AutoCloseable.

  "These variable" should be "These variables."

• Under "Practice Multi-Catch"
  the for-loop bounds for the code snippet
  comparing a "Multi-catch example - handling multiple exception types with one handler" and an intended-to-be-equivalent "separate catch blocks for the same exceptions" example,
  appear unintentionally different.

  Given shared input data between the two examples:

  String[] testData = {"10", "abc", "0", "5", "hello"};
  int[] divisors = {2, 2, 1, 0, 3};
  

  The first part with multi-catch uses:

  for (int i = 0; i < testData.length && i < divisors.length; i++)

  whereas the second part with multiple catch blocks uses:

  for (int i = 0; i < 2 && i < testData.length; i++)

  which appears to accidentally have i<2 rather than i< divisors.length meaning the 2nd example doesn't match the first example in also throwing and catching the ArithmeticExceptions,
  which would be handled fine. Substituting the original bounds in the 2nd example within the snippet works fine, so this looks like a possible mistake during the development of the example by the authors (the comparison is incomplete as 2 is less than divisors.length which == testData.length == 5 so not all the exceptions that could be compared are compared between the two approaches).

---

Feel free to leave the issue open after making any changes as I can review fixes and submit any possible additional finds as I continue to review the material.

Thanks so much!

[JosePaumard]

Thank you again for your review! I just pushed a fix.

[willy-b]

Great - I have verified your fixes for the aforementioned items except for the following couple of small issues!

---

For the latest https://dev.java/learn/exceptions/catching-handling/ (archived as is at https://web.archive.org/web/20260505182924/https://dev.java/learn/exceptions/catching-handling/?cache=false ):

• The new sentence added on JDK 22 support for unnamed "_" exceptions in exception handlers has a typo:
  In

  Note that, starting with JDK 22 you can also give set the unnamed variable to your handlers

  "give set" should be "give" and the sentence is missing a period at the end

• The updated code example to show use of the unnamed exception type "_" appears to have a possible typo as in

  } catch (Exception _) {
  // starting with JDK 22 you use the unnamed variable
  // to avoid accidental use of your exception variable
  

  "you use" should probably be "you can use" (as the unnamed variable is not a required practice nor is exhaustive catching of exception types thrown, some may be allowed to be thrown intentionally while catching others).

• In the sentence

  The try-with-resources Statement section has more information.

  Thanks for adding a hyperlink but I worry my intended direction here was misunderstood as instead of a link to the "try-with-resources Statement section" being added, a link to "Suppressed Exceptions" (only given as an example of an existing hyperlink to a same-page section) has been substituted, which I think was not the intention of the author.
  That is to say, the sentence in context was:

  Consider using the try-with-resources statement in these situations, which automatically releases system resources when no longer needed. The try-with-resources Statement section [needs hyperlink] has more information.

  And has been updated to, as of https://web.archive.org/web/20260505182924/https://dev.java/learn/exceptions/catching-handling/?cache=false :

  Consider using the try-with-resources statement in these situations, which automatically releases system resources when no longer needed. You can check the section Suppressed Exceptions to learn more about the try-with-resources statement.

  But probably should be:

  Consider using the try-with-resources statement in these situations, which automatically releases system resources when no longer needed. The try-with-resources Statement section has more information. ]

• Under "Practice Multi-catch" the example has not quite been updated appropriately as of https://web.archive.org/web/20260505182924/https://dev.java/learn/exceptions/catching-handling/?cache=false#multi-catching​

​

I had written:

the for-loop bounds for the code snippet
comparing a "Multi-catch example - handling multiple exception types with one handler" and an intended-to-be-equivalent "separate catch blocks for the same exceptions" example,
appear unintentionally different.
Given shared input data between the two examples:

String[] testData = {"10", "abc", "0", "5", "hello"};
int[] divisors = {2, 2, 1, 0, 3};

The first part with multi-catch uses:

for (int i = 0; i < testData.length && i < divisors.length; i++)

whereas the second part with multiple catch blocks uses:

for (int i = 0; i < 2 && i < testData.length; i++)

which appears to accidentally have i<2 rather than i< divisors.length meaning the 2nd example doesn't match the first example in also throwing and catching the ArithmeticExceptions,
which would be handled fine. Substituting the original bounds in the 2nd example within the snippet works fine, so this looks like a possible mistake during the development of the example by the authors (the comparison is incomplete as 2 is less than divisors.length which == testData.length == 5 so not all the exceptions that could be compared are compared between the two approaches).

In response to the above, an update was made by your team such that it now (as of https://web.archive.org/web/20260505182924/https://dev.java/learn/exceptions/catching-handling/?cache=false ) has for the second part of the example showing:

IO.println("=== Same Logic with Separate Catches ===");
for (int i = 0; i < testData.length && i < testData.length; i++) {

With i < testData.length repeated twice in the same condition (redundant).

But this should be:

IO.println("=== Same Logic with Separate Catches ===");
for (int i = 0; i < testData.length && i < divisors.length; i++) {

with i < divisors.length included, though divisors.length happens to be equal to testData.length so you could also consider to check just one or a single variable capturing the length of both, but definitely should not be redundantly checking the same array variable length twice in the same for condition.

---

Thanks very much!

[JosePaumard]

Thank you again for your report! I just pushed a fix.

[willy-b]

Thanks. The new sentence on JDK 22 is missing a period at the end but is otherwise fixed ( https://web.archive.org/web/20260507004143/https://dev.java/learn/exceptions/catching-handling/ ).

Additionally there remain a couple of section references without hyperlinks just in case you want to add them before I close this:

---

In the latest version of https://dev.java/learn/exceptions/throwing/ (archived as is at https://web.archive.org/web/20260506193428/https://dev.java/learn/exceptions/throwing/?cache=false ) ,

• In the sentence

  For more information, see the Chained Exceptions section.

  "Chained Exceptions" should be hyperlinked to https://dev.java/learn/exceptions/throwing/#chained-exceptions .

• In the sentence

  The section Unchecked Exceptions — The Controversy discusses why most applications shouldn't throw runtime exceptions or subclass RuntimeException.

  "Unchecked Exceptions — The Controversy" should be hyperlinked to https://dev.java/learn/exceptions/unchecked-exception-controversy/ .

---

Thanks very much!

[JosePaumard]

Thank you again for your report! I just pushed a fix.

[willy-b]

Thanks, I can confirm all items so far reported above were resolved in your latest versions.

I found one more typo while reviewing to close:

---

In the latest version of https://dev.java/learn/exceptions/catching-handling/ (archived as is at https://web.archive.org/web/20260508022613/https://dev.java/learn/exceptions/catching-handling/ ).

The sentence

Because the BufferedReader instance is declared in a try-with-resource statement, it will be closed regardless of whether the try statement completes normally or abruptly (as a result of the method BufferedReader.readLine() throwing an IOException.

Is missing a closing parenthesis.

---

Thanks very much!

[JosePaumard]

Thank you again for your report! I just pushed a fix.

[willy-b]

Thanks very much!

---

I can confirm that https://web.archive.org/web/20260508193106/https://dev.java/learn/exceptions/catching-handling/
fixes the missing closing parenthesis as it now reads:

Because the BufferedReader instance is declared in a try-with-resource statement, it will be closed regardless of whether the try statement completes normally or abruptly (as a result of the method BufferedReader.readLine()) throwing an IOException.

(Though, to be honest I expected it to close after "IOException", this is also valid and demonstrates why it is good to ask rather than assume!)

---

However, it is noticed that in the latest https://dev.java/learn/exceptions/catching-handling/ (archived at https://web.archive.org/web/20260508193106/https://dev.java/learn/exceptions/catching-handling/ )

in the sentences

If you try to compile the ListOfNumbers class, the compiler prints an error message about the exception thrown by the FileWriter constructor.

and

The new FileWriter statement fails and throws an IOException.

the mentions of FileWriter are linked to the documentation for FilterWriter instead by mistake ("File" is getting substituted with "Filter"), which you may want to fix before this is closed.

Thanks!