Implement Errno system

This commit adds onto 679e0de0

If an exception is thrown, the exception message might not contain the full errors. Individual failures may get added to suppressed throwables. FileUtils functions previously just returned the exception message as errmsg which did not contain full error info.

Now `Error` class has been implemented which will used to return errors, including suppressed throwables. Each `Error` object will have an error type, code, message and a list of throwables in case multiple throwables need to returned, in addition to the suppressed throwables list in each throwable.

A supportive `Errno` base class has been implemented as well which other errno classes can inherit of which some have been added. Each `Errno` object will have an error type, code and message and can be converted to an `Error` object if needed.

Requirement for `Context` object has been removed from FileUtils so that they can be called from anywhere in code instead of having to pass around `Context` objects. Previously, `string.xml` was used to store error messages in case multi language support had to be added in future since error messages are displayed to users and not just for dev usage. However, now this will have to handled in java code if needed, based on locale.

The termux related file utils have also been moved from FileUtils to TermuxFileUtils

termux-shared/src/main/java/com/termux/shared/models/errors/Errno.java

@@ -0,0 +1,89 @@
+package com.termux.shared.models.errors;
+
+import android.app.Activity;
+
+import androidx.annotation.NonNull;
+
+import com.termux.shared.logger.Logger;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+/** The {@link Class} that defines error messages and codes. */
+public class Errno {
+
+    public static final String TYPE = "Error";
+
+
+    public static final Errno ERRNO_SUCCESS = new Errno(TYPE, Activity.RESULT_OK, "Success");
+    public static final Errno ERRNO_MINOR_FAILURES = new Errno(TYPE, Activity.RESULT_FIRST_USER, "Minor failure");
+    public static final Errno ERRNO_FAILED = new Errno(TYPE, Activity.RESULT_FIRST_USER + 1, "Failed");
+    public static final Errno ERRNO_CANCELED = new Errno(TYPE, Activity.RESULT_FIRST_USER + 2, "Cancelled");
+
+    /** The errno type. */
+    protected String type;
+    /** The errno code. */
+    protected final int code;
+    /** The errno message. */
+    protected final String message;
+
+    private static final String LOG_TAG = "Errno";
+
+
+    public Errno(final String type, final int code, final String message) {
+        this.type = type;
+        this.code = code;
+        this.message = message;
+    }
+
+    @NonNull
+    @Override
+    public String toString() {
+        return "type=" + type + ", code=" + code + ", message=\"" + message + "\"";
+    }
+
+
+    public String getType() {
+        return type;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public int getCode() {
+        return code;
+    }
+
+
+
+    public Error getError() {
+        return new Error(getType(), getCode(), getMessage());
+    }
+
+    public Error getError(Object... args) {
+        try {
+            return new Error(getType(), getCode(), String.format(getMessage(), args));
+        } catch (Exception e) {
+            Logger.logWarn(LOG_TAG, "Exception raised while calling String.format() for error message of errno " + this + " with args" + Arrays.toString(args) + "\n" + e.getMessage());
+            // Return unformatted message as a backup
+            return new Error(getType(), getCode(), getMessage() + ": " + Arrays.toString(args));
+        }
+    }
+
+    public Error getError(Throwable throwable, Object... args) {
+        return getError(Collections.singletonList(throwable), args);
+    }
+
+    public Error getError(List<Throwable> throwablesList, Object... args) {
+        try {
+            return new Error(getType(), getCode(), String.format(getMessage(), args), throwablesList);
+        } catch (Exception e) {
+            Logger.logWarn(LOG_TAG, "Exception raised while calling String.format() for error message of errno " + this + " with args" + Arrays.toString(args) + "\n" + e.getMessage());
+            // Return unformatted message as a backup
+            return new Error(getType(), getCode(), getMessage() + ": " + Arrays.toString(args), throwablesList);
+        }
+    }
+
+}

termux-shared/src/main/java/com/termux/shared/models/errors/Error.java

@@ -0,0 +1,249 @@
+package com.termux.shared.models.errors;
+
+import androidx.annotation.NonNull;
+
+import com.termux.shared.logger.Logger;
+import com.termux.shared.markdown.MarkdownUtils;
+
+import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+public class Error implements Serializable {
+
+    /** The error type. */
+    private String type;
+    /** The error code. */
+    private int code;
+    /** The error message. */
+    private String message;
+    /** The error exceptions. */
+    private List<Throwable> throwablesList = new ArrayList<>();
+
+    private static final String LOG_TAG = "Error";
+
+
+    public Error() {
+        InitError(null, null, null, null);
+    }
+
+    public Error(String type, Integer code, String message, List<Throwable> throwablesList) {
+        InitError(type, code, message, throwablesList);
+    }
+
+    public Error(String type, Integer code, String message, Throwable throwable) {
+        InitError(type, code, message, Collections.singletonList(throwable));
+    }
+
+    public Error(String type, Integer code, String message) {
+        InitError(type, code, message, null);
+    }
+
+    public Error(Integer code, String message, List<Throwable> throwablesList) {
+        InitError(null, code, message, throwablesList);
+    }
+
+    public Error(Integer code, String message, Throwable throwable) {
+        InitError(null, code, message, Collections.singletonList(throwable));
+    }
+
+    public Error(Integer code, String message) {
+        InitError(null, code, message, null);
+    }
+
+    public Error(String message, Throwable throwable) {
+        InitError(null, null, message, Collections.singletonList(throwable));
+    }
+
+    public Error(String message, List<Throwable> throwablesList) {
+        InitError(null, null, message, throwablesList);
+    }
+
+    public Error(String message) {
+        InitError(null, null, message, null);
+    }
+
+    private void InitError(String type, Integer code, String message, List<Throwable> throwablesList) {
+        if (type != null && !type.isEmpty())
+            this.type = type;
+        else
+            this.type = Errno.TYPE;
+
+        if (code != null && code > Errno.ERRNO_SUCCESS.getCode())
+            this.code = code;
+        else
+            this.code = Errno.ERRNO_SUCCESS.getCode();
+
+        this.message = message;
+        this.throwablesList = throwablesList;
+    }
+
+
+    public String getType() {
+        return type;
+    }
+
+    public Integer getCode() {
+        return code;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public void prependMessage(String message) {
+        if (message != null && isStateFailed())
+            this.message = message + this.message;
+    }
+
+    public void appendMessage(String message) {
+        if (message != null && isStateFailed())
+            this.message = this.message + message;
+    }
+
+    public List<Throwable> getThrowablesList() {
+        return Collections.unmodifiableList(throwablesList);
+    }
+
+
+    public synchronized boolean setStateFailed(@NonNull Error error) {
+        return setStateFailed(error.getType(), error.getCode(), error.getMessage(), null);
+    }
+
+    public synchronized boolean setStateFailed(@NonNull Error error, Throwable throwable) {
+        return setStateFailed(error.getType(), error.getCode(), error.getMessage(), Collections.singletonList(throwable));
+    }
+    public synchronized boolean setStateFailed(@NonNull Error error, List<Throwable> throwablesList) {
+        return setStateFailed(error.getType(), error.getCode(), error.getMessage(), throwablesList);
+    }
+
+    public synchronized boolean setStateFailed(int code, String message) {
+        return setStateFailed(this.type, code, message, null);
+    }
+
+    public synchronized boolean setStateFailed(int code, String message, Throwable throwable) {
+        return setStateFailed(this.type, code, message, Collections.singletonList(throwable));
+    }
+
+    public synchronized boolean setStateFailed(int code, String message, List<Throwable> throwablesList) {
+        return setStateFailed(this.type, code, message, throwablesList);
+    }
+
+    public synchronized boolean setStateFailed(String type, int code, String message, List<Throwable> throwablesList) {
+        this.message = message;
+        this.throwablesList = throwablesList;
+
+        if (type != null && !type.isEmpty())
+            this.type = type;
+
+        if (code > Errno.ERRNO_SUCCESS.getCode()) {
+            this.code = code;
+            return true;
+        } else {
+            Logger.logWarn(LOG_TAG, "Ignoring invalid error code value \"" + code + "\". Force setting it to RESULT_CODE_FAILED \"" + Errno.ERRNO_FAILED.getCode() + "\"");
+            this.code = Errno.ERRNO_FAILED.getCode();
+            return false;
+        }
+    }
+
+    public boolean isStateFailed() {
+        return code > Errno.ERRNO_SUCCESS.getCode();
+    }
+
+
+    @NonNull
+    @Override
+    public String toString() {
+        return getErrorLogString(this);
+    }
+
+    /**
+     * Get a log friendly {@link String} for {@link Error} error parameters.
+     *
+     * @param error The {@link Error} to convert.
+     * @return Returns the log friendly {@link String}.
+     */
+    public static String getErrorLogString(final Error error) {
+        if (error == null) return "null";
+
+        StringBuilder logString = new StringBuilder();
+
+        logString.append(error.getCodeString());
+        logString.append("\n").append(error.getTypeAndMessageLogString());
+        if (error.throwablesList != null)
+            logString.append("\n").append(error.geStackTracesLogString());
+
+        return logString.toString();
+    }
+
+    /**
+     * Get a minimal log friendly {@link String} for {@link Error} error parameters.
+     *
+     * @param error The {@link Error} to convert.
+     * @return Returns the log friendly {@link String}.
+     */
+    public static String getMinimalErrorLogString(final Error error) {
+        if (error == null) return "null";
+
+        StringBuilder logString = new StringBuilder();
+
+        logString.append(error.getCodeString());
+        logString.append(error.getTypeAndMessageLogString());
+
+        return logString.toString();
+    }
+
+    /**
+     * Get a minimal {@link String} for {@link Error} error parameters.
+     *
+     * @param error The {@link Error} to convert.
+     * @return Returns the {@link String}.
+     */
+    public static String getMinimalErrorString(final Error error) {
+        if (error == null) return "null";
+
+        StringBuilder logString = new StringBuilder();
+
+        logString.append("(").append(error.getCode()).append(") ");
+        logString.append(error.getType()).append(": ").append(error.getMessage());
+
+        return logString.toString();
+    }
+
+    /**
+     * Get a markdown {@link String} for {@link Error}.
+     *
+     * @param error The {@link Error} to convert.
+     * @return Returns the markdown {@link String}.
+     */
+    public static String getErrorMarkdownString(final Error error) {
+        if (error == null) return "null";
+
+        StringBuilder markdownString = new StringBuilder();
+
+        markdownString.append(MarkdownUtils.getSingleLineMarkdownStringEntry("Error Code", error.getCode(), "-"));
+        markdownString.append("\n").append(MarkdownUtils.getMultiLineMarkdownStringEntry((Errno.TYPE.equals(error.getType()) ? "Error Message" : "Error Message (" + error.getType() + ")"), error.message, "-"));
+        markdownString.append("\n\n").append(error.geStackTracesMarkdownString());
+
+        return markdownString.toString();
+    }
+
+
+    public String getCodeString() {
+        return Logger.getSingleLineLogStringEntry("Error Code", code, "-");
+    }
+
+    public String getTypeAndMessageLogString() {
+        return Logger.getMultiLineLogStringEntry(Errno.TYPE.equals(type) ? "Error Message" : "Error Message (" + type + ")", message, "-");
+    }
+
+    public String geStackTracesLogString() {
+        return Logger.getStackTracesString("StackTraces:", Logger.getStackTracesStringArray(throwablesList));
+    }
+
+    public String geStackTracesMarkdownString() {
+        return Logger.getStackTracesMarkdownString("StackTraces", Logger.getStackTracesStringArray(throwablesList));
+    }
+
+}

termux-shared/src/main/java/com/termux/shared/models/errors/FileUtilsErrno.java

@@ -0,0 +1,81 @@
+package com.termux.shared.models.errors;
+
+/** The {@link Class} that defines FileUtils error messages and codes. */
+public class FileUtilsErrno extends Errno {
+
+    public static final String TYPE = "FileUtils Error";
+
+
+    /* Errors for null or empty paths (100-150) */
+    public static final Errno ERRNO_EXECUTABLE_REQUIRED = new Errno(TYPE, 100, "Executable required.");
+    public static final Errno ERRNO_NULL_OR_EMPTY_REGULAR_FILE_PATH = new Errno(TYPE, 101, "The regular file path is null or empty.");
+    public static final Errno ERRNO_NULL_OR_EMPTY_REGULAR_FILE = new Errno(TYPE, 102, "The regular file is null or empty.");
+    public static final Errno ERRNO_NULL_OR_EMPTY_EXECUTABLE_FILE_PATH = new Errno(TYPE, 103, "The executable file path is null or empty.");
+    public static final Errno ERRNO_NULL_OR_EMPTY_EXECUTABLE_FILE = new Errno(TYPE, 104, "The executable file is null or empty.");
+    public static final Errno ERRNO_NULL_OR_EMPTY_DIRECTORY_FILE_PATH = new Errno(TYPE, 105, "The directory file path is null or empty.");
+    public static final Errno ERRNO_NULL_OR_EMPTY_DIRECTORY_FILE = new Errno(TYPE, 106, "The directory file is null or empty.");
+
+
+
+    /* Errors for invalid or not found files at path (150-200) */
+    public static final Errno ERRNO_FILE_NOT_FOUND_AT_PATH = new Errno(TYPE, 150, "The %1$s is not found at path \"%2$s\".");
+
+    public static final Errno ERRNO_NO_REGULAR_FILE_FOUND = new Errno(TYPE, 151, "Regular file not found at %1$s path.");
+    public static final Errno ERRNO_NOT_A_REGULAR_FILE = new Errno(TYPE, 152, "The %1$s at path \"%2$s\" is not a regular file.");
+
+    public static final Errno ERRNO_NON_REGULAR_FILE_FOUND = new Errno(TYPE, 153, "Non-regular file found at %1$s path.");
+    public static final Errno ERRNO_NON_DIRECTORY_FILE_FOUND = new Errno(TYPE, 154, "Non-directory file found at %1$s path.");
+    public static final Errno ERRNO_NON_SYMLINK_FILE_FOUND = new Errno(TYPE, 155, "Non-symlink file found at %1$s path.");
+
+    public static final Errno ERRNO_FILE_NOT_AN_ALLOWED_FILE_TYPE = new Errno(TYPE, 156, "The %1$s found at path \"%2$s\" is not one of allowed file types \"%3$s\".");
+
+    public static final Errno ERRNO_VALIDATE_FILE_EXISTENCE_AND_PERMISSIONS_FAILED_WITH_EXCEPTION = new Errno(TYPE, 157, "Validating file existence and permissions of %1$s at path \"%2$s\" failed.\nException: %3$s");
+    public static final Errno ERRNO_VALIDATE_DIRECTORY_EXISTENCE_AND_PERMISSIONS_FAILED_WITH_EXCEPTION = new Errno(TYPE, 158, "Validating directory existence and permissions of %1$s at path \"%2$s\" failed.\nException: %3$s");
+
+
+
+    /* Errors for file creation (200-250) */
+    public static final Errno ERRNO_CREATING_FILE_FAILED = new Errno(TYPE, 200, "Creating %1$s at path \"%2$s\" failed.");
+    public static final Errno ERRNO_CREATING_FILE_FAILED_WITH_EXCEPTION = new Errno(TYPE, 201, "Creating %1$s at path \"%2$s\" failed.\nException: %3$s");
+
+    public static final Errno ERRNO_CANNOT_OVERWRITE_A_NON_SYMLINK_FILE_TYPE = new Errno(TYPE, 202, "Cannot overwrite %1$s while creating symlink at \"%2$s\" to \"%3$s\" since destination file type \"%4$s\" is not a symlink.");
+    public static final Errno ERRNO_CREATING_SYMLINK_FILE_FAILED_WITH_EXCEPTION = new Errno(TYPE, 203, "Creating %1$s at path \"%2$s\" to \"%3$s\" failed.\nException: %4$s");
+
+
+
+    /* Errors for file copying and moving (250-300) */
+    public static final Errno ERRNO_COPYING_OR_MOVING_FILE_FAILED_WITH_EXCEPTION = new Errno(TYPE, 250, "%1$s from \"%2$s\" to \"%3$s\" failed.\nException: %4$s");
+    public static final Errno ERRNO_COPYING_OR_MOVING_FILE_TO_SAME_PATH = new Errno(TYPE, 251, "%1$s from \"%2$s\" to \"%3$s\" cannot be done since they point to the same path.");
+    public static final Errno ERRNO_CANNOT_OVERWRITE_A_DIFFERENT_FILE_TYPE = new Errno(TYPE, 252, "Cannot overwrite %1$s while %2$s it from \"%3$s\" to \"%4$s\" since destination file type \"%5$s\" is different from source file type \"%6$s\".");
+    public static final Errno ERRNO_CANNOT_MOVE_DIRECTORY_TO_SUB_DIRECTORY_OF_ITSELF = new Errno(TYPE, 253, "Cannot move %1$s from \"%2$s\" to \"%3$s\" since destination is a subdirectory of the source.");
+
+
+
+    /* Errors for file deletion (300-350) */
+    public static final Errno ERRNO_DELETING_FILE_FAILED = new Errno(TYPE, 300, "Deleting %1$s at path \"%2$s\" failed.");
+    public static final Errno ERRNO_DELETING_FILE_FAILED_WITH_EXCEPTION = new Errno(TYPE, 301, "Deleting %1$s at path \"%2$s\" failed.\nException: %3$s");
+    public static final Errno ERRNO_CLEARING_DIRECTORY_FAILED_WITH_EXCEPTION = new Errno(TYPE, 302, "Clearing %1$s at path \"%2$s\" failed.\nException: %3$s");
+    public static final Errno ERRNO_FILE_STILL_EXISTS_AFTER_DELETING = new Errno(TYPE, 303, "The %1$s still exists after deleting it from \"%2$s\".");
+
+
+
+    /* Errors for file reading and writing (350-400) */
+    public static final Errno ERRNO_READING_STRING_TO_FILE_FAILED_WITH_EXCEPTION = new Errno(TYPE, 350, "Reading string from %1$s at path \"%2$s\" failed.\nException: %3$s");
+    public static final Errno ERRNO_WRITING_STRING_TO_FILE_FAILED_WITH_EXCEPTION = new Errno(TYPE, 351, "Writing string to %1$s at path \"%2$s\" failed.\nException: %3$s");
+    public static final Errno ERRNO_UNSUPPORTED_CHARSET = new Errno(TYPE, 352, "Unsupported charset \"%1$s\"");
+    public static final Errno ERRNO_CHECKING_IF_CHARSET_SUPPORTED_FAILED = new Errno(TYPE, 353, "Checking if charset \"%1$s\" is supported failed.\nException: %2$s");
+
+
+
+    /* Errors for invalid file permissions (400-450) */
+    public static final Errno ERRNO_INVALID_FILE_PERMISSIONS_STRING_TO_CHECK = new Errno(TYPE, 400, "The file permission string to check is invalid.");
+    public static final Errno ERRNO_FILE_NOT_READABLE = new Errno(TYPE, 401, "The %1$s at path is not readable. Permission Denied.");
+    public static final Errno ERRNO_FILE_NOT_WRITABLE = new Errno(TYPE, 402, "The %1$s at path is not writable. Permission Denied.");
+    public static final Errno ERRNO_FILE_NOT_EXECUTABLE = new Errno(TYPE, 403, "The %1$s at path is not executable. Permission Denied.");
+
+
+    FileUtilsErrno(final String type, final int code, final String message) {
+        super(type, code, message);
+    }
+
+}

termux-shared/src/main/java/com/termux/shared/models/errors/FunctionErrno.java

@@ -0,0 +1,20 @@
+package com.termux.shared.models.errors;
+
+/** The {@link Class} that defines function error messages and codes. */
+public class FunctionErrno extends Errno {
+
+    public static final String TYPE = "Function Error";
+
+
+    /* Errors for null or empty parameters (100-150) */
+    public static final Errno ERRNO_NULL_OR_EMPTY_PARAMETER = new Errno(TYPE, 100, "The %1$s parameter passed to \"%2$s\" is null or empty.");
+    public static final Errno ERRNO_NULL_OR_EMPTY_PARAMETERS = new Errno(TYPE, 101, "The %1$s parameters passed to \"%2$s\" are null or empty.");
+    public static final Errno ERRNO_UNSET_PARAMETER = new Errno(TYPE, 102, "The %1$s parameter passed to \"%2$s\" must be set.");
+    public static final Errno ERRNO_UNSET_PARAMETERS = new Errno(TYPE, 103, "The %1$s parameters passed to \"%2$s\" must be set.");
+
+
+    FunctionErrno(final String type, final int code, final String message) {
+        super(type, code, message);
+    }
+
+}