feat: Introduce AggregateException

Allows multiple exceptions to be handled

AnkiDroid/src/main/java/com/ichi2/exceptions/AggregateException.kt

@@ -0,0 +1,50 @@
+/*
+ *  Copyright (c) 2022 David Allison <davidallisongithub@gmail.com>
+ *
+ *  This program is free software; you can redistribute it and/or modify it under
+ *  the terms of the GNU General Public License as published by the Free Software
+ *  Foundation; either version 3 of the License, or (at your option) any later
+ *  version.
+ *
+ *  This program is distributed in the hope that it will be useful, but WITHOUT ANY
+ *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ *  PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License along with
+ *  this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.ichi2.exceptions
+
+import java.lang.Exception
+import java.lang.RuntimeException
+
+/**
+ * An exception which describes separate failures.
+ * For example: if an operation should continue after some errors, but those errors would stop
+ * the successful completion of an operation
+ */
+class AggregateException(message: String, val exceptions: List<Exception>) : RuntimeException(message) {
+
+    companion object {
+        /**
+         * Returns an [AggregateException] containing the provided exceptions
+         * Or: returns the single exception is the provided list contains a single element
+         *
+         * @param message the message to include in the returned [AggregateException] (unused if only one exception provided)
+         * @param exceptions the exceptions to include in the [AggregateException]
+         * @throws IllegalStateException if [exceptions] is empty
+         */
+        fun raise(message: String, exceptions: List<Exception>): Exception {
+            if (exceptions.isEmpty()) {
+                throw IllegalStateException("no exceptions provided ")
+            }
+
+            if (exceptions.size == 1) {
+                return exceptions.single()
+            }
+
+            return AggregateException(message, exceptions)
+        }
+    }
+}

AnkiDroid/src/test/java/com/ichi2/exceptions/AggregateExceptionTest.kt

@@ -0,0 +1,57 @@
+/*
+ *  Copyright (c) 2022 David Allison <davidallisongithub@gmail.com>
+ *
+ *  This program is free software; you can redistribute it and/or modify it under
+ *  the terms of the GNU General Public License as published by the Free Software
+ *  Foundation; either version 3 of the License, or (at your option) any later
+ *  version.
+ *
+ *  This program is distributed in the hope that it will be useful, but WITHOUT ANY
+ *  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+ *  PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License along with
+ *  this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package com.ichi2.exceptions
+
+import com.ichi2.testutils.TestException
+import com.ichi2.testutils.assertThrows
+import org.hamcrest.MatcherAssert.assertThat
+import org.hamcrest.Matchers.equalTo
+import org.hamcrest.Matchers.instanceOf
+import org.junit.Test
+
+/**
+ * Test for [AggregateException]
+ */
+class AggregateExceptionTest {
+    @Test
+    fun exceptionIfNoElementsProvided() {
+        assertThrows<IllegalStateException> { AggregateException.raise("", emptyList()) }
+    }
+
+    @Test
+    fun providedExceptionReturnedIfSingletonListProvided() {
+        val expectedResult = TestException("a")
+        val result = AggregateException.raise("", listOf(expectedResult))
+
+        assertThat(result, equalTo(expectedResult))
+    }
+
+    @Test
+    fun aggregateExceptionContainsAllExceptions() {
+        val first = TestException("a")
+        val second = TestException("b")
+        val result = AggregateException.raise("message", listOf(first, second))
+
+        assertThat(result, instanceOf(AggregateException::class.java))
+
+        val asAggregateException = result as AggregateException
+
+        assertThat(asAggregateException.message, equalTo("message"))
+        assertThat(asAggregateException.exceptions[0], equalTo(first))
+        assertThat(asAggregateException.exceptions[1], equalTo(second))
+    }
+}