Refactor and Improve Exception Handling (#115)

These changes significantly enhances the exception handling capabilities of the JMatrix library. It introduces configurable auto-raise behavior, updates Javadocs for clarity and completeness, and refactors existing exception mechanisms for robustness. These changes provide developers with more control over error handling, improve documentation, and ensure the library's reliability in managing exceptions.

Signed-off-by: Ryuu Mitsuki <[email protected]>

Author: mitsuki31

src/main/java/com/mitsuki/jmatrix/Matrix.java

@@ -0,0 +1,221 @@
+/*
+ * Copyright (c) 2023-2024 Ryuu Mitsuki
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.mitsuki.jmatrix.enums;
+
+import com.mitsuki.jmatrix.Matrix;
+import com.mitsuki.jmatrix.exception.*;
+
+/**
+ * The {@code JMErrorCode} enum represents error codes for various error conditions
+ * that can occur within a <b>JMatrix</b> library. Each error code is associated with
+ * an integer error number, a string representation of the error code, and a descriptive
+ * error message.
+ *
+ * <p>This enum provides methods to retrieve the error number, error code, and error message.
+ * Additionally, it provides a static method to convert an error number or a string
+ * representation of the error code back to its corresponding {@code JMErrorCode} enum value,
+ * it is declared as {@link #valueOf(Object)}. The method does not throws an error if the type
+ * of value is unrecognized, instead it returns {@code null}.
+ *
+ * <p><b>Example usage:</b>
+ * <pre>&nbsp;
+ *   JMErrorCode errorCode = JMErrorCode.INVIDX;
+ *   int errno = errorCode.getErrno();        // 201
+ *   String errcode = errorCode.getCode();    // INVIDX
+ *   String errmsg = errorCode.getMessage();  // Given index is out bounds
+ * </pre>
+ *
+ * <p>Get the error code from a thrown exception:
+ * <pre>&nbsp;
+ *   try {
+ *      Matrix m = new Matrix();
+ *      m = Matrix.mult(m, 5);
+ *   } catch (Exception e) {
+ *      if (e instanceof JMatrixBaseException) {
+ *          e = (JMatrixBaseException) e;
+ *          String errcode = e.getErrorCode().getCode();  // NULLMT
+ *      }
+ *   }
+ * </pre>
+ *
+ * @since    1.5.0
+ * @version  1.0, 05 June 2024
+ * @author   <a href="https://github.com/mitsuki31" target="_blank">
+ *           Ryuu Mitsuki</a>
+ * @license  <a href="https://www.apache.org/licenses/LICENSE-2.0" target="_blank">
+ *           Apache License 2.0</a>
+ * @see      java.lang.Enum
+ */
+public enum JMErrorCode {
+    /**
+     * Error code indicating that the given index is out of bounds.
+     *
+     * <p>This error code is useful to indicates that user gives an index
+     * either of row or column (which from methods that indexing-related,
+     * such as {@link Matrix#insertRow(int, double[])}, {@link
+     * Matrix#dropColumn(int)}, and {@link Matrix#display(int)}).
+     *
+     * <p><b>Error number:</b> {@code 201}
+     * <p><b>Related exception:</b> {@link InvalidIndexException}
+     */
+    INVIDX( 0xD3 ^ (0xD + 0xD), "Given index is out of bounds" ),
+    /**
+     * Error code indicating that the matrix has an invalid type.
+     *
+     * <p>This error code will be in the {@link IllegalMatrixSizeException} exception
+     * which related to invalid type of matrix. For example, user attempting to
+     * calculate trace with a {@code 5x3} matrix, which is an illegal attemption
+     * because trace calculation are only for square matrices.
+     *
+     * <p><b>Error number:</b> {@code 202}
+     * <p><b>Related exception:</b> {@link IllegalMatrixSizeException}
+     */
+    INVTYP( 0xD3 ^ (0xD + 0xC), "Matrix has invalid type of matrix" ),
+    /**
+     * Error code indicating that the matrix is {@code null} or the matrix
+     * entries is {@code null}.
+     *
+     * <p>A matrix with {@code null} entries can be constructed using
+     * {@link Matrix#Matrix()} constructor, which is not require any arguments.
+     * Thus, the returned matrix is a matrix with a {@code null} entries (in other
+     * words, an uninitialized matrix).
+     *
+     * <p><b>Error number:</b> {@code 203}
+     * <p><b>Related exception:</b> {@link NullMatrixException}
+     */
+    NULLMT( 0xD3 ^ (0xD + 0xB), "Matrix is null" ),
+    /**
+     * Error code indicating an unknown error.
+     *
+     * <p>This error code can be made by the {@link JMatrixBaseException} class
+     * when failed to evaluate the given error number (errno) or the cause exception
+     * is not an instance of that class while trying to get the error code from the
+     * given cause exception, and ended up constructs with this error code.
+     *
+     * <p><b>Error number:</b> {@code 400}
+     * <p><b>Related exception:</b> {@link JMatrixBaseException}
+     */
+    UNKERR( ((0xD3 << 1) - (0xF & 0xF) - 0b111), "Unknown error" );
+
+    /** The error nuumber stored for later retrieval by {@link #getErrno()} */
+    private int errno = 0x00;
+    /** The error code stored for later retrieval by {@link #getCode()} */
+    private String code = null;
+    /** The error message stored for later retrieval by {@link #getMessage()} */
+    private String message = null;
+
+    /**
+     * Constructs a {@code JMErrorCode} with the specified error number and detail message.
+     *
+     * @param errno    The error number associated with this error code.
+     * @param message  The descriptive error message associated with this error code.
+     *
+     * @since  1.5.0
+     */
+    JMErrorCode(int errno, String message) {
+        this.code = super.toString();
+        this.errno = errno;
+        this.message = message;
+    }
+
+    /**
+     * Returns the error number associated with this error code.
+     *
+     * @return  The error number.
+     *
+     * @since   1.5.0
+     * @see     #getErrnoStr()
+     */
+    public int getErrno() {
+        return this.errno;
+    }
+
+    /**
+     * Returns the error number as a string in the format {@code JM###}.
+     *
+     * @return  The error number as a string, prefixed with {@code JM}.
+     *
+     * @since   1.5.0
+     * @see     #getErrno()
+     */
+    public String getErrnoStr() {
+        return "JM" + this.errno;  // Return: JM###
+    }
+
+    /**
+     * Returns the string representation of this error code.
+     *
+     * @return  The error code.
+     *
+     * @since   1.5.0
+     */
+    public String getCode() {
+        return this.code;
+    }
+
+    /**
+     * Returns the descriptive error message associated with this error code.
+     *
+     * @return  The descriptive error message.
+     *
+     * @since   1.5.0
+     */
+    public String getMessage() {
+        return this.message;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since  1.5.0
+     */
+    @Override
+    public String toString() {
+        return String.format("%s[%s]", this.code, this.errno);
+    }
+
+    /**
+     * Returns the {@code JMErrorCode} corresponding to the specified value.
+     *
+     * <p>The value can be either an integer (error number) or a string (error code).
+     * If the type of {@code x} is not recognized, this method returns {@code null}.
+     *
+     * @param  <T>  The type of value, which can be either {@link Integer} or {@link String}.
+     * @param  x    The value to be evaluated.
+     *
+     * @return      The corresponding {@code JMErrorCode}, or {@code null} if the type of
+     *              {@code x} is not known.
+     *
+     * @throws  IllegalArgumentException  If this enum has no constant with the specified
+     *                                    name (with string representation).
+     *
+     * @since   1.5.0
+     * @see     Enum#valueOf(Class, String)
+     */
+    public static <T extends Object> JMErrorCode valueOf(T x) {
+        if (x instanceof Integer) {
+            for (JMErrorCode ec : JMErrorCode.values()) {
+                if ((Integer) x == ec.getErrno()) return ec;
+            }
+        } else if (x instanceof String) {
+            // This might throws an `IllegalArgumentException`
+            return JMErrorCode.valueOf((String) x);
+        }
+        //* No error being thrown if got unknown type, but return `null`
+        return null;
+    }
+}