jupyter/chapter16-exception.ipynb

{
  "cells": [{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["# Exception\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["In Java, an exception is a mechanism to signal that the\n", "execution of a method can not be performed\n", "by example, trying to get a value of a list with an index equals to -1\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["String valueAt(List<String> list, int index) {\n", "  return list.get(index);\n", "}\n", "valueAt(List.of(\"hello\"), -1);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["an exception has\n", "- a type that indicate the kind of error\n", "- an error message that explain in English the issue\n", "- a stacktrace which indicates where the exception was raised\n", "  and the methods to reach that point\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["In our example, `java.lang.IndexOutOfBoundsException` is the type,\n", "`Index: -1 Size: 1` is the message and\n", "```\n", "at ImmutableCollections$AbstractImmutableList.outOfBounds (ImmutableCollections.java:201)\n", "at ImmutableCollections$List12.get (ImmutableCollections.java:418)\n", "at valueAt (#1:2)\n", "at (#2:1)\n", "```\n", "is the stacktrace\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## `throw`\n", "You can create (with `new`) and raise your own exception using the keyword `throw`\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["String valueAt(List<String> list, int index) {\n", "  if (index < 0 || index >= list.size()) {\n", "    throw new IllegalArgumentException(\"invalid index \" + index);\n", "  }\n", "  return list.get(index);\n", "}\n", "valueAt(List.of(\"hello\"), -1);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["The stacktrace is populated automatically when you create the exception\n", "not where you throw it so it's a good idea to create the exception\n", "not too far from where you throw it.\n", "In the following example, the stacktrace will say that the exception\n", "is created at `notTooFar (#5:2)`, on the second line, not at `notTooFar (#5:4)`.\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["void notTooFar() {\n", "  var exception = new RuntimeException(\"i'm created here\");\n", "  // an empty line\n", "  throw exception;\n", "}\n", "notTooFar();\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## Use existing exceptions\n", "While you can create your own exception (see below),\n", "usually we are re-using already existing exceptions.\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["Exceptions commonly used in Java\n", "- NullPointerException if a reference is null\n", "- IllegalArgumentException if an argument of a method is not valid\n", "- IllegalStateException if the object state doesn't allow to proceed,\n", "  by example if a file is closed, you can not read it\n", "- AssertionError if a code that should not be reached has been reached\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["By example\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["enum State { OK, NOT_OK }\n", "void testState(State state) {\n", "  switch(state) {\n", "    case OK -> System.out.println(\"Cool !\");\n", "    case NOT_OK -> System.out.println(\"Not cool\");\n", "    default -> { throw new AssertionError(\"Danger, Will Robinson\"); }\n", "  }\n", "}\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["here the AssertionError can only be thrown if the code if testState()\n", "and the enum State disagree on set of possible values\n", "By example, if a new state is added\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["enum State { OK, NOT_OK, UNKNOWN }\n", "testState(State.UNKNOWN);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## Recovering from an exception\n", "In Java, you can recover from an exception using a `try/catch` block.\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["URI uri;\n", "try {\n", "  uri = new URI(\"http://i'm a malformed uri\");\n", "} catch(URISyntaxException e) {\n", "  // if the URI is malformed, used google by default\n", "  uri = new URI(\"http://www.google.fr\");\n", "}\n", "System.out.println(uri);\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["A common mistake is to write a `try/catch` in a method with an empty catch\n", "or a catch that log/print a message instead of actually recovering from the\n", "exception\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["As a rule of thumb, if you can not write something meaningful in the catch\n", "block then you should not use a `try/catch`.\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## Fighting with the compiler\n", "For the compiler, there are two kinds of exceptions that are handled differently\n", "- unchecked exception, you can throw them anywhere you want\n", "- checked exception, you can only throw them if\n", "  - you are inside a method that declare to throws that exception (or a supertype)\n", "  - you are inside a try/catch block on that exception (or a supertype)\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["In Java, an exception that inherits from `RuntimeException` or `Error` are\n", "unchecked exceptions, all the others are checked exceptions \n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["so this code doesn't compile because `IOException` inherits from `Exception`\n", "and not `RuntimeException`. \n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["/*\n", "void hello() {\n", "  Files.delete(Path.of(\"I don't exist\"));\n", "}\n", "*/\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["A way to fix the issue is to use the keywords `throws` to ask the caller\n", "of the method to deal with the exception, again the caller will have,\n", "either by propagating it with a `throws` or recover from it with a `try/catch`.\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["void hello() throws IOException {\n", "  Files.delete(Path.of(\"I don't exist\"));\n", "}\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["As a rule of thumb, 99% of the time you want to propagate the exception,\n", "and keep the number of `try/catch` as low as possible in your program,\n", "so prefer `throws` to `try/catch`.\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["### When you can not use `throws`, wrap the exception\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["If a method has it's signature fixed because it overrides a method of an interface,\n", "then you can not use `throws`\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["The following example doesn't compile because the method `run` of a `Runnable`\n", "doesn't declare to `throws` `IOException` so the only solution seems to be\n", "to use a `try/catch`.\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["/*\n", "var aRunnable = new Runnable() {\n", "  public void run() {\n", "    Files.delete(Path.of(\"I don't exist\"));\n", "  }\n", "};\n", "*/\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["So here, we have to use a `try/catch` but we still want to propagate the exception.\n", "The trick is wrap the checked exception into an unchecked exception.\n", "This trick is so common that the Java API already comes with existing\n", "classes to wrap common checked exceptions. For `IOException`, the unchecked\n", "equivalent is `UncheckedIOException`. \n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["var aRunnable = new Runnable() {\n", "  public void run() {\n", "    try {\n", "      Files.delete(Path.of(\"I don't exist\"));\n", "    } catch(IOException e) {\n", "      // the way to recover, is to propagate it as an unchecked\n", "      throw new UncheckedIOException(e);\n", "    }\n", "  }\n", "};\n", "aRunnable.run();\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["The exception `UndeclaredThrowableException` is used as the generic unchecked exception\n", "to wrap any checked exception which do not have an unchecked equivalent.\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["## Create your own Exception\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["You can create your own exception by creating a class that inherits from `RuntimeException`\n", "You should provide at least two constructors, one with a message and one with a message\n", "and a cause.\n"]
}
,
{
  "cell_type": "code",
  "execution_count": null,
  "metadata": {},
  "outputs": [],
  "source": ["public class MyException extends RuntimeException {\n", "  public MyException(String message) {\n", "    super(message);\n", "  }\n", "  public MyException(String message, Throwable cause) {\n", "    super(message, cause);\n", "  }\n", "}\n", "throw new MyException(\"This is my exception\");\n"]
}
,
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["But in general, don't ! Reuse existing commonly used exceptions.\n"]
}
],
  "metadata": {
    "kernelspec": {
      "display_name": "Java",
      "language": "java",
      "name": "java"
    },
    "language_info": {
      "codemirror_mode": "java",
      "file_extension": ".java",
      "mimetype": "text/x-java-source",
      "name": "Java",
      "pygments_lexer": "java",
      "version": "15"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 2
}