1861 exception handling (exercism#2022)

rv02 · web-flow · commit e1d46b956b7d · 2021-09-15T07:28:56.000-07:00
* Adding CalculatorConundrum exercise for exception-handling concept exercise.

* moved into reference/java

* Made changes iter 1.

* shifted calculation from constructor to CalculatorConundrum.calculate()

* 2nd iter changes

* removed cause from some of thrown exceptions, updated readme, added config.json

* added newline

* Modified instructions.md, Added missing files

* Modifying docs, config.json, renamed introduction.md
diff --git a/config.json b/config.json
@@ -85,6 +85,20 @@
         ],
         "status": "active"
       },
+      {
+        "slug": "calculator-conundrum",
+        "name": "Calculator Conundrum",
+        "uuid": "9e62feec-c2c3-4fd6-94f5-0574cc65447d",
+        "concepts": [
+          "exception-handling"
+        ],
+        "prerequisites": [
+          "conditionals",
+          "switch-case",
+          "basics"
+        ],
+        "status": "wip"
+      },
       {
         "slug": "squeaky-clean",
         "name": "Squeaky Clean",
diff --git a/exercises/concept/calculator-conundrum/.docs/hints.md b/exercises/concept/calculator-conundrum/.docs/hints.md
@@ -0,0 +1,18 @@
+# Hints
+
+## 1. Implement the method calculate to support a few basic operations
+
+* Use a `switch-case` block to match different operations and implement them using the `SimpleOperation` class.
+
+## 2. Handle illegal operations
+
+
+* Check for `null` operations before the switch.
+* Add a case to the switch for the empty String.
+* Use a default for anything else at the end of the switch.
+* Throw an `IllegalOpertionException` with appropriate messages in different cases.
+
+## 3. Handle the thrown DivideByZero exceptions
+
+* Use a `try-catch` block to catch `ArithmeticException`
+* Pass both the `message` and the `ArithmeticException` as the `cause` parameter when throwing the exception.
diff --git a/exercises/concept/calculator-conundrum/.docs/instructions.md b/exercises/concept/calculator-conundrum/.docs/instructions.md
@@ -0,0 +1,45 @@
+# Instructions
+
+In this exercise you will be building error handling for a simple integer calculator. 
+To make matters simple, methods for calculating addition, multiplication and division are provided.
+
+The goal is to have a working calculator that returns a String with the following pattern: `16 + 51 = 67`, when provided with arguments `16`, `51` and `+`.
+
+```java
+CalculatorConundrum obj = new CalculatorConundrum();
+
+obj.calculate(16, 51, "+"); // => returns "16 + 51 = 67"
+
+obj.calculate(32, 6, "*"); // => returns "32 * 6 = 192"
+
+obj.calculate(512, 4, "/"); // => returns "512 / 4 = 128"
+```
+
+## 1. Implement the method calculate to support a few basic operations 
+
+The main method for implementation in this task will be the `CalculatorConundrum.calculate()` method. 
+It takes three arguments. 
+The first two arguments are integer numbers on which an operation is going to operate. 
+The third argument is of type String and for this exercise it is necessary to implement the following operations:
+
+- addition using the `+` String
+- multiplication using the `*` String
+- division using the `/` String
+
+## 2. Handle illegal operations
+
+All the following cases need to throw an `IllegalOperationException`:
+
+* when the `operation` argument is `null`, with the String `Operation cannot be null` as the`message` parameter 
+* when the `operation` is the empty String, with the String `Operation cannot be empty` as the `message` parameter
+* when the `operation` argument is anything other than `+`, `*`, or `/`,  with the String `{invalidOperation} operation does not exist` as the `message` parameter
+
+## 3. Handle the thrown DivideByZero exceptions
+
+Dividing by zero throws an `ArithmeticException` which the calculator needs to catch and then throw an `IllegalOperationException` with the message `Divide by zero operation illegal` and the `ArithmeticException` as its cause.
+This should be handled using a `try-catch` block. 
+Any other exception should not be handled by the `CalulatorConundrum.calculate()` method.
+
+```java
+CalculatorConundrum.calculate(512, 0, "/"); // => throws IllegalOperationException with message "Division by zero is not allowed."
+```
diff --git a/exercises/concept/calculator-conundrum/.docs/introduction.md b/exercises/concept/calculator-conundrum/.docs/introduction.md
@@ -0,0 +1,142 @@
+# Exception Handling in Java
+
+Exception Handling in Java is one of the powerful mechanism to handle errors so that the normal flow of the application can be maintained.
+Good exception handling can re-route the program to give the user still a positive experience.
+
+## Why use Exception Handling with an example
+
+```java
+public static List<Player> getPlayers() throws IOException {
+    Path path = Paths.get("players.dat");
+    List<String> players = Files.readAllLines(path);
+
+    return players.stream()
+      .map(Player::new)
+      .collect(Collectors.toList());
+}
+```
+
+This code chooses not to handle the IOException, passing it up the call stack instead. 
+In an idealized environment, the code works fine.
+
+But what might happen in production if players.dat is missing?
+
+```log
+Exception in thread "main" java.nio.file.NoSuchFileException: players.dat <-- players.dat file doesn't exist
+    at sun.nio.fs.WindowsException.translateToIOException(Unknown Source)
+    at sun.nio.fs.WindowsException.rethrowAsIOException(Unknown Source)
+    // ... more stack trace
+    at java.nio.file.Files.readAllLines(Unknown Source)
+    at java.nio.file.Files.readAllLines(Unknown Source)
+    at Exceptions.getPlayers(Exceptions.java:12) <-- Exception arises in getPlayers() method, on line 12
+    at Exceptions.main(Exceptions.java:19) <-- getPlayers() is called by main(), on line 19
+```
+
+We must handle these conditions because they affect the flow of the application negatively and form exceptions.
+
+## Types of Java Exceptions
+
+There are mainly two types of exceptions: checked and unchecked. An error is considered as the unchecked exception. However, according to Oracle, there are three types of exceptions namely:
+
+1. Checked Exception
+2. Unchecked Exception
+3. Error
+
+### 1. Checked Exception
+The classes that directly inherit the Throwable class except RuntimeException and Error are known as checked exceptions. 
+For example, IOException, SQLException, etc. Checked exceptions are checked at compile-time.
+
+### 2. Unchecked Exception
+The classes that inherit the RuntimeException are known as unchecked exceptions. 
+For example, ArithmeticException, NullPointerException, ArrayIndexOutOfBoundsException, etc. 
+Unchecked exceptions are not checked at compile-time, but they are checked at runtime.
+
+### 3. Error
+Error is irrecoverable. 
+Some example of errors are OutOfMemoryError, VirtualMachineError, AssertionError etc.
+
+## Handling Exceptions
+
+### Try-Catch block
+
+The `try` statement allows you to define a block of code to be tested for errors while it is being executed.
+
+The `catch` statement allows you to define a block of code to be executed, if an error occurs in the try block.
+
+For example:
+```java
+public int getPlayerScore(String playerFile) {
+    try {
+        Scanner contents = new Scanner(new File(playerFile));
+        return Integer.parseInt(contents.nextLine());
+    } catch (FileNotFoundException noFile) {
+        throw new IllegalArgumentException("File not found", noFile);
+    }
+}
+```
+
+### The Throw/Throws keyword
+
+If a method does not handle a checked exception, the method must declare it using the `throws` keyword. 
+The `throws` keyword appears at the end of a method's signature.
+
+You can throw an exception, either a newly instantiated one or an exception that you just caught, by using the `throw` keyword.
+
+#### Example
+```java
+import java.io.*;
+public class className {
+
+   public void deposit(double amount) throws RemoteException {
+      // Method implementation
+      throw new RemoteException();
+   }
+   // Remainder of class definition
+}
+```
+
+### Finally
+
+The `finally` statement (optional) lets you execute code, after `try...catch`, **regardless of the result**.
+
+#### Example
+
+```java
+public class Main {
+  public static void main(String[] args) {
+    try {
+      int[] myNumbers = {1, 2, 3};
+      System.out.println(myNumbers[10]);
+    } catch (Exception e) {
+      System.out.println("Something went wrong.");
+    } finally {
+      System.out.println("The 'try catch' is finished.");
+    }
+  }
+}
+```
+
+The output will be:
+
+```
+Something went wrong.
+The 'try catch' is finished. 
+```
+
+## User-Defined Exceptions
+
+You can create your own exceptions in Java. 
+Keep the following points in mind when writing your own exception classes −
+
+* All exceptions must be a child of Throwable.
+
+* If you want to write a checked exception that is automatically enforced by the Handle or Declare Rule, you need to extend the Exception class.
+
+* If you want to write a runtime exception, you need to extend the RuntimeException class.
+
+We can define our own Exception class as below:
+
+```java
+class MyException extends Exception {
+}
+```
diff --git a/exercises/concept/calculator-conundrum/.meta/config.json b/exercises/concept/calculator-conundrum/.meta/config.json
@@ -0,0 +1,25 @@
+{
+  "blurb": "Learn about exception-handling by making a simple calculator.",
+  "authors": [
+    "rv02",
+    "jmrunkle"
+  ],
+  "files": {
+    "solution": [
+      "src/main/java/CalculatorConundrum.java"
+    ],
+    "test": [
+      "src/test/java/CalculatorConundrumTest.java"
+    ],
+    "exemplar": [
+      ".meta/src/reference/java/CalculatorConundrum.java"
+    ],
+    "editor": [
+      "src/main/java/IllegalOperationException.java",
+      "src/main/java/SimpleOperation.java"
+    ]
+  },
+  "forked_from": [
+    "csharp/calculator-conundrum"
+  ]
+}
diff --git a/exercises/concept/calculator-conundrum/.meta/design.md b/exercises/concept/calculator-conundrum/.meta/design.md
@@ -0,0 +1,25 @@
+# Design
+
+## Learning Objectives
+
+* Know the concept of exception handling in java
+* Know how to implement and handle exception in different ways
+
+## Out of scope 
+
+* finally
+
+## Concepts
+
+* exception-handling
+* try-catch
+* throw and throws keyword
+* user-defined exceptions
+
+## Prerequisites
+
+* `basics`: know how to define methods.
+* `conditionals`: know how to do conditional logic.
+* `switch-case`: know how to work with a switch-case conditionals.
+
+
diff --git a/exercises/concept/calculator-conundrum/.meta/src/reference/java/CalculatorConundrum.java b/exercises/concept/calculator-conundrum/.meta/src/reference/java/CalculatorConundrum.java
@@ -0,0 +1,30 @@
+public class CalculatorConundrum {
+
+    public String calculate(int operand1, int operand2, String operation) {
+        int result;
+        if (operation == null) {
+            throw new IllegalOperationException("Operation cannot be null");
+        }
+        switch (operation) {
+            case "+":
+                result = SimpleOperation.addition(operand1, operand2);
+                break;
+            case "*":
+                result = SimpleOperation.multiplication(operand1, operand2);
+                break;
+            case "/":
+                try {
+                    result = SimpleOperation.division(operand1, operand2);
+                } catch (ArithmeticException e) {
+                    throw new IllegalOperationException("Divide by zero operation illegal", e);
+                }
+                break;
+            case "":
+                throw new IllegalOperationException("Operation cannot be empty");
+            default:
+                throw new IllegalOperationException(String.format("%s operation does not exist", operation));
+        }
+        return String.format("%d %s %d = %s", operand1, operation, operand2, result);
+    }
+
+}
diff --git a/exercises/concept/calculator-conundrum/build.gradle b/exercises/concept/calculator-conundrum/build.gradle
@@ -0,0 +1,24 @@
+apply plugin: "java"
+apply plugin: "eclipse"
+apply plugin: "idea"
+
+// set default encoding to UTF-8
+compileJava.options.encoding = "UTF-8"
+compileTestJava.options.encoding = "UTF-8"
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testImplementation "junit:junit:4.13"
+    testImplementation "org.assertj:assertj-core:3.15.0"
+}
+
+test {
+    testLogging {
+        exceptionFormat = 'short'
+        showStandardStreams = true
+        events = ["passed", "failed", "skipped"]
+    }
+}
diff --git a/exercises/concept/calculator-conundrum/src/main/java/CalculatorConundrum.java b/exercises/concept/calculator-conundrum/src/main/java/CalculatorConundrum.java
@@ -0,0 +1,6 @@
+class CalculatorConundrum {
+
+    public String calculate(int operand1, int operand2, String operation) {
+        throw new UnsupportedOperationException("Please implement the CalculatorConundrum.calculate() method");
+    }
+}
diff --git a/exercises/concept/calculator-conundrum/src/main/java/IllegalOperationException.java b/exercises/concept/calculator-conundrum/src/main/java/IllegalOperationException.java
@@ -0,0 +1,11 @@
+public class IllegalOperationException extends RuntimeException {
+
+    public IllegalOperationException(String errorMessage) {
+        super(errorMessage);
+    }
+
+    public IllegalOperationException(String errorMessage, Throwable cause) {
+        super(errorMessage, cause);
+    }
+}
+
diff --git a/exercises/concept/calculator-conundrum/src/main/java/SimpleOperation.java b/exercises/concept/calculator-conundrum/src/main/java/SimpleOperation.java
@@ -0,0 +1,17 @@
+class SimpleOperation {
+    public static int division(int operand1, int operand2)
+    {
+        return operand1 / operand2;
+    }
+
+    public static int multiplication(int operand1, int operand2)
+    {
+        return operand1 * operand2;
+    }
+
+    public static int addition(int operand1, int operand2)
+    {
+        return operand1 + operand2;
+    }
+}
+
diff --git a/exercises/concept/calculator-conundrum/src/test/java/CalculatorConundrumTest.java b/exercises/concept/calculator-conundrum/src/test/java/CalculatorConundrumTest.java
