Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8046734

Exceptions pages need cleanup

    XMLWordPrintable

    Details

    • Type: Enhancement
    • Status: Closed
    • Priority: P2
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 8u40
    • Component/s: docs
    • Subcomponent:
    • Verification:
      Verified

      Description

      ====
      http://docs.oracle.com/javase/tutorial/essential/exceptions/handling.html

      1. The exceptions listed on this page are correct (keep in mind for future reference)

       * IOException (raised by): PrintWriter out = new PrintWriter(new FileWriter("OutFile.txt"));
       * IndexOutOfBoundsException (raised by): out.println("Value at: " + i + " = " + list.get(i));

      Code example in subsequent pages shouldn't be throwing different exceptions than this.

      Suggest adding a comment next to each of the above lines, telling the user what exception will be thrown.

      Also note that the example is now using Collections (specifically ArrayList).


      ====
      http://docs.oracle.com/javase/tutorial/essential/exceptions/try.html

      1. Page contains code snippets, some of which belong in writeList() method. But the
      way it currently reads is confusing because the method declaration has been omitted, and there
      are no "..." indicating that some code is intentionally missing.

      Suggest adding in the writeList method to put the code where it belongs:

      CURRENT:

      private List<Integer> list;
      private static final int SIZE = 10;

      PrintWriter out = null;

      try {
          System.out.println("Entered try statement");
          out = new PrintWriter(new FileWriter("OutFile.txt"));
          for (int i = 0; i < SIZE; i++) {
              out.println("Value at: " + i + " = " + list.get(i));
          }
      }

      catch and finally statements . . .

      CHANGE TO:

      private List<Integer> list;
      private static final int SIZE = 10;

      public void writeList() {
          PrintWriter out = null;
          try {
              System.out.println("Entered try statement");
              out = new PrintWriter(new FileWriter("OutFile.txt"));
              for (int i = 0; i < SIZE; i++) {
                  out.println("Value at: " + i + " = " + list.get(i));
              }
          }
          catch and finally statements . . .
      }

      2. The page says both "catch and finally blocks" and "catch and finally statements"
         Use "block" to provide consistency with the other pages.

      =====
      http://docs.oracle.com/javase/tutorial/essential/exceptions/catch.html

      1. This page shows an example that catches FileNotFoundException. Yet the
      previous pages describe that only IOException and IndexOutOfBoundsException
      would need to be caught. Replace FileNotFoundException with IndexOutOfBoundsException.
      (BTW compilation fails when attempting to catch FileNotFoundException, but passes when
      catching IndexOutOfBoundsException).


      http://javapubs.us.oracle.com/people/shommel/ws/tutorial-dec-2013/src/essential/exceptions/finally.html

      1. This text is wrong:
      "The vector.elementAt(i) statement fails and throws an ArrayIndexOutOfBoundsException."
      It's wrong because the example doesn't use vector anymore.
      It uses ArrayList.get(), which throws IndexOutOfBoundsException:
      "out.println("Value at: " + i + " = " + list.get(i));"
      Apparently the original version of this lesson did use vector, but this part never got updated when the first page changed to use collections.

      2. This code suggests throwing a user-defined exception (SampleException), but doing that at
      this point in the tutorial is distracting:

       catch (FileNotFoundException e) {
          System.err.println("FileNotFoundException: " + e.getMessage());
          throw new SampleException(e);

      There are a couple of sentences describing this below, but only as a forward reference (as in "throwing
      exceptions is covered later") or something vague, like "You might want to do this
      if you want your program to handle an exception in this situation in a specific way."

      Suggest removing this example of throwing a custom exception here; save that for the
      page about throwing exceptions. Let's keep this page focused on catching exceptions.

      Question: Do we need to say anything about the order of the catch blocks? Does one
      specific kind of exception need to be caught before others? Or does the order not matter?

      ===============
      http://docs.oracle.com/javase/tutorial/essential/exceptions/finally.html

      1. Item 2 still mentions vector.elementAt(i) and ArrayIndexOutOfBoundsException.
      Change this to list.get(i) and IndexOutOfBoundsException

      2. What's the point of the last "Don't do this" example? It doesn't provide
      a recommended best practice, but rather, only shows something you shouldn't do. Suggest removing
      this part because it makes the overall concept seem more complicated than it
      really is. Plus, it contains mention of FileNotFoundException and ArrayIndexOutOfBoundsException
      which isn't thrown by the example anyway.

      =============================
      http://docs.oracle.com/javase/tutorial/essential/exceptions/putItTogether.html

      This page is still using Vector and ArrayIndexOutOfBoundsException.
      Make consistent with previous pages by changing to ArrayList and IndexOutOfBoundsException

        Attachments

          Activity

            People

            Assignee:
            shommel Scott Hommel (Inactive)
            Reporter:
            shommel Scott Hommel (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Dates

              Due:
              Created:
              Updated:
              Resolved: