Package org.daiitech.naftah.errors

Class ExceptionUtils

java.lang.Object
org.daiitech.naftah.errors.ExceptionUtils
public final class ExceptionUtils extends Object
Utility class for exception-related helper methods.

This class provides static methods to retrieve the root cause or the most specific cause of an exception, as well as a factory method to create a custom NaftahBugError related to invalid loop labels.

Note: This class cannot be instantiated. Attempting to instantiate it will always throw a NaftahBugError.

Author:
Chakib Daii

  • Field Details

    • INFINITE_DECIMAL_ERROR

      public static final String INFINITE_DECIMAL_ERROR
      Error message indicating an overflow in a decimal number. The value provided is infinite and thus invalid. Example message format: "تجاوز في العدد العشري: القيمة غير نهائية للمدخل 'value'."
      See Also:

    • NAN_DECIMAL_ERROR

      public static final String NAN_DECIMAL_ERROR
      Error message indicating that the value is Not-a-Number (NaN). Example message format: "القيمة ليست رقمًا (NaN): 'value'"
      See Also:

    • UNSUPPORTED_BITWISE_DECIMAL_ERROR

      public static final String UNSUPPORTED_BITWISE_DECIMAL_ERROR
      Error message indicating that bitwise operations are not supported on decimal (floating point) numbers. The message includes the value and the attempted operation. Example message format: "العمليات الثنائية (bitwise) غير مدعومة على الأعداد ذات الفاصلة العشرية: 'value' operation،"
      See Also:

    • EMPTY_ARGUMENT_ERROR

      public static final String EMPTY_ARGUMENT_ERROR
      Error message indicating that a single argument is empty. Arabic: "لا يمكن أن يكون الوسيط فارغًا."
      See Also:

    • EMPTY_ARGUMENTS_ERROR

      public static final String EMPTY_ARGUMENTS_ERROR
      Error message indicating that multiple arguments are empty. Arabic: "لا يمكن أن تكون الوسائط فارغة."
      See Also:

    • NOTE

      public static final String NOTE
      Note prefix used in error messages.

      Arabic: "ملاحظة:"

      See Also:

    • INVALID_INSTANCE_METHOD_CALL_MSG

      public static final BiFunction<String,String,String> INVALID_INSTANCE_METHOD_CALL_MSG
      Generates an error message indicating that an instance method was called incorrectly.

      The message is in Arabic and explains that the method is not static and requires the first argument (or second if the method is from a list of functions) to be the instance on which the method will be invoked.

      Usage example: 

       String msg = INVALID_INSTANCE_METHOD_CALL_MSG.apply("methodName", additionalInfo);

      Parameters:

      • First: the method name (%s)
      • Second: additional context or details (%s)

  • Constructor Details

    • ExceptionUtils

      private ExceptionUtils()
      Private constructor to prevent instantiation. Always throws a NaftahBugError when called.

  • Method Details

    • getRootCause

      public static Throwable getRootCause(Throwable original)
      Returns the root cause of the given Throwable.

      Traverses the causal chain to find the deepest cause of the throwable. If the original throwable is null, returns null.

      Parameters:
      original - the throwable to inspect
      Returns:
      the root cause throwable, or null if none found or if original is null

    • getMostSpecificCause

      public static Throwable getMostSpecificCause(Throwable original)
      Returns the most specific cause of the given Throwable.

      This method returns the deepest cause (root cause) if available, otherwise returns the original throwable.

      Parameters:
      original - the throwable to inspect
      Returns:
      the most specific cause (root cause if present) or the original throwable

    • newNaftahBugInvalidLoopLabelError

      public static NaftahBugError newNaftahBugInvalidLoopLabelError(String label, org.antlr.v4.runtime.Parser parser, int line, int column)
      Creates a new NaftahBugError indicating an invalid reuse of a loop label.

      Constructs an error message in Arabic describing that the same loop label cannot be used in the specified statement.

      Parameters:
      label - the loop label name that was reused
      parser - the parser instance used to obtain vocabulary information
      Returns:
      a new NaftahBugError with a localized error message

    • newNaftahBugInvalidUsageError

      public static NaftahBugError newNaftahBugInvalidUsageError()
      Creates a new NaftahBugError indicating that an invalid usage has occurred.
      Returns:
      a NaftahBugError describing the invalid usage error

    • newNaftahBugNullInputError

      public static NaftahBugError newNaftahBugNullInputError(boolean singleInput, Object... args)
      Creates a new NaftahBugError indicating that a required input argument is null or missing.

      This method selects the appropriate error message depending on whether the error is related to a single input or multiple inputs.

      Parameters:
      singleInput - true if the error is due to a single missing input argument; false if multiple input arguments are missing.
      Returns:
      a NaftahBugError instance with the corresponding error message.

    • newNaftahBugInvalidNumberConversionOverflowError

      public static NaftahBugError newNaftahBugInvalidNumberConversionOverflowError(boolean overflow, Number number, Class<?> targetClass)
      Raise an overflow exception for the given number and target class.
      Parameters:
      number - the number we tried to convert
      targetClass - the target class we tried to convert to
      Throws:
      IllegalArgumentException - if there is an overflow

    • newNaftahBugInvalidNumberValueError

      public static NaftahBugError newNaftahBugInvalidNumberValueError(Object object)
      Creates a new NaftahBugError indicating that the given object represents an invalid numeric value.
      Parameters:
      object - the invalid numeric value
      Returns:
      a NaftahBugError describing the invalid number value error

    • newNaftahBugInvalidNumberValueError

      public static NaftahBugError newNaftahBugInvalidNumberValueError(Object object, Exception exception)
      Creates a new NaftahBugError for an invalid numeric value, with the cause.

      This method provides more detail by attaching the underlying Exception that caused the failure (e.g., NumberFormatException).

      Parameters:
      object - the invalid numeric value
      exception - the underlying exception (can be null)
      Returns:
      a NaftahBugError describing the error with the given cause

    • newNaftahBugInvalidNumberValueError

      public static NaftahBugError newNaftahBugInvalidNumberValueError(Object object, int radix)
      Creates a new NaftahBugError for an invalid numeric value in a specific radix.

      This is useful when parsing fails for a given base (e.g., base 16, base 10), and you want to include the radix in the error message.

      Parameters:
      object - the invalid numeric value
      radix - the number system base (e.g., 10 for decimal)
      Returns:
      a NaftahBugError describing the error for the specified radix

    • newNaftahBugInvalidNumberValueError

      public static NaftahBugError newNaftahBugInvalidNumberValueError(Object object, int radix, Exception exception)
      Creates a new NaftahBugError for an invalid numeric value in a specific radix, including the underlying cause.

      This is the most detailed version, allowing you to specify the erroneous value, the radix used during parsing, and the original exception that triggered the failure.

      Parameters:
      object - the invalid numeric value
      radix - the number system base in which parsing was attempted
      exception - the root exception that caused the error (nullable)
      Returns:
      a NaftahBugError describing the full error context

    • newNaftahBugUnsupportedNumbersError

      public static NaftahBugError newNaftahBugUnsupportedNumbersError(boolean singleInput, DynamicNumber... dn)
      Creates a new NaftahBugError indicating that one or more numeric types are unsupported.
      Parameters:
      singleInput - whether the error is for a single input (true) or multiple inputs (false)
      dn - the dynamic numbers involved in the error
      Returns:
      a NaftahBugError describing the unsupported number type(s) error

    • newNaftahBugUnsupportedBitwiseDecimalError

      public static NaftahBugError newNaftahBugUnsupportedBitwiseDecimalError(boolean singleInput, DynamicNumber... dn)
      Creates a NaftahBugError indicating that bitwise operations on decimal numbers are unsupported.
      Parameters:
      dn - the decimal numbers on which the bitwise operation was attempted
      Returns:
      a NaftahBugError with an explanatory message

    • newNaftahKeyNotFoundError

      public static NaftahBugError newNaftahKeyNotFoundError(Object key)
      Creates a new NaftahBugError indicating that the specified key was not found in the associative array.
      Parameters:
      key - the key that was not found
      Returns:
      a NaftahBugError describing the missing key error

    • newNaftahNegativeNumberError

      public static NaftahBugError newNaftahNegativeNumberError()
      Creates a new NaftahBugError indicating that negative numbers are not allowed.
      Returns:
      a NaftahBugError describing the disallowed negative number error

    • newNaftahUnsupportedFunctionError

      public static NaftahBugError newNaftahUnsupportedFunctionError(String functionName, Class<?> functionClass, int line, int column)
      Creates a new NaftahBugError indicating that the specified function is not supported.
      Parameters:
      functionName - the name of the unsupported function.
      functionClass - the class providing the function.
      line - the line number in the source code where the error occurred.
      column - the column number in the source code where the error occurred.
      Returns:
      a NaftahBugError describing the unsupported function.

    • newNaftahIllegalArgumentError

      public static NaftahBugError newNaftahIllegalArgumentError(String functionName, String providerClassName, int paramCount, int argCount, String functionDetailedString, Exception e, int line, int column)
      Creates a new NaftahBugError for illegal argument count or mismatched argument types.
      Parameters:
      functionName - the name of the function being invoked.
      providerClassName - the class providing the function.
      paramCount - the expected number of parameters.
      argCount - the actual number of arguments provided.
      functionDetailedString - detailed string representation of the function.
      e - the underlying exception, if any.
      line - the line number where the error occurred.
      column - the column number where the error occurred.
      Returns:
      a NaftahBugError describing the illegal argument error.

    • newNaftahInvocationError

      public static NaftahBugError newNaftahInvocationError(String functionName, String functionDetailedString, Exception e, int line, int column)
      Creates a new NaftahBugError for errors occurring during function invocation.
      Parameters:
      functionName - the name of the function being invoked.
      functionDetailedString - detailed string representation of the function.
      e - the underlying exception.
      line - the line number where the error occurred.
      column - the column number where the error occurred.
      Returns:
      a NaftahBugError describing the invocation error.

    • newNaftahNonInvocableFunctionError

      public static NaftahBugError newNaftahNonInvocableFunctionError(String functionName, String functionDetailedString, int line, int column)
      Creates a new NaftahBugError for functions that are not invocable.
      Parameters:
      functionName - the name of the function.
      functionDetailedString - detailed string representation of the function.
      line - the line number where the error occurred.
      column - the column number where the error occurred.
      Returns:
      a NaftahBugError describing the non-invocable function error.

    • newNaftahInstantiationError

      public static NaftahBugError newNaftahInstantiationError(String functionName, String functionDetailedString, Exception e, int line, int column)
      Creates a new NaftahBugError when object instantiation fails.
      Parameters:
      functionName - the name of the function triggering instantiation.
      functionDetailedString - detailed string representation of the function.
      e - the underlying exception.
      line - the line number where the error occurred.
      column - the column number where the error occurred.
      Returns:
      a NaftahBugError describing the instantiation failure.

    • newNaftahInvocableNotFoundError

      public static NaftahBugError newNaftahInvocableNotFoundError(String functionName, int line, int column)
      Creates and throws a new NaftahBugError when the requested invocable (method or constructor) cannot be found in the current context.

      The generated error message (in Arabic) indicates that the target callable symbol is undefined or inaccessible.

      Parameters:
      functionName - the name of the missing invocable (method or constructor).
      line - the source line number where the error occurred.
      column - the source column number where the error occurred.
      Returns:
      this method never returns normally; it always throws a NaftahBugError.
      Throws:
      NaftahBugError - always thrown to indicate a missing invocable.

    • newNaftahInvocableNotFoundError

      public static NaftahBugError newNaftahInvocableNotFoundError(String functionName)
      Creates a new NaftahBugError for a missing invocable without specifying source line or column.
      Parameters:
      functionName - the name of the missing invocable (method or constructor)
      Returns:
      never returns normally; this method always creates a NaftahBugError
      Throws:
      NaftahBugError - always thrown to indicate a missing invocable

    • newNaftahInvocableListFoundError

      public static <T extends JvmExecutable> NaftahBugError newNaftahInvocableListFoundError(String functionName, Collection<T> functionsOrClassInitializers, Throwable exception, int line, int column)
      Creates and throws a NaftahBugError when a collection of invocable functions or class initializers is found, but the caller did not specify an index to select which one to invoke.

      This is typically used for overloaded or indexed functions. The generated error message (in Arabic) explains how to select a specific version using a numeric index appended after the function name with a colon.

      The message includes a numbered list of all available invocable versions for reference.

      Type Parameters:
      T - type of JvmExecutable in the collection
      Parameters:
      functionName - the name of the function or class initializer
      functionsOrClassInitializers - a collection of available overloaded or indexed invocables
      exception - the original exception that triggered this error, for context
      line - the source line number where the error occurred
      column - the source column number where the error occurred
      Returns:
      this method never returns normally; it always throws a NaftahBugError
      Throws:
      NaftahBugError - always thrown to indicate ambiguity in the invocable list

    • newNaftahSingleExpressionAssignmentError

      public static NaftahBugError newNaftahSingleExpressionAssignmentError(int line, int column)
      Creates and throws a NaftahBugError when an assignment expression is invalid because it is not provided as a tuple of elements.

      This error is triggered in situations where the user provides either:

      • a single value for assignment instead of a tuple, or
      • multiple comma-separated values that are not wrapped in a tuple structure.

      The generated message (in Arabic) informs the user that an assignment expression must always be represented as a tuple, regardless of whether the assignment involves a single value or multiple values.

      Parameters:
      line - the source line number where the error occurred
      column - the source column number where the error occurred
      Returns:
      this method never returns normally; it always throws NaftahBugError
      Throws:
      NaftahBugError - always thrown to indicate an invalid assignment expression

    • newNaftahExpressionsDeclarationsSizeMismatchErrorError

      public static NaftahBugError newNaftahExpressionsDeclarationsSizeMismatchErrorError(int line, int column)
      Creates and throws a NaftahBugError when the number of assignment expressions does not match the number of declared variables.

      This typically occurs when performing multiple assignments or tuple-based destructuring, and the left-hand side declarations and right-hand side expressions do not align in count.

      The generated message (in Arabic) clarifies that both sides must have an equal number of elements.

      Parameters:
      line - the source line number where the error occurred
      column - the source column number where the error occurred
      Returns:
      this method never returns normally; it always throws NaftahBugError
      Throws:
      NaftahBugError - always thrown to indicate a mismatch between declarations and expressions

    • newNaftahSpecifiedTypesExceedVariableNamesError

      public static NaftahBugError newNaftahSpecifiedTypesExceedVariableNamesError(int line, int column)
      Creates and throws a NaftahBugError when the parser encounters multiple variable declarations where the number of explicitly specified types exceeds the number of declared variable names.

      This situation is invalid because each declared variable may have at most one corresponding type, and extra types cannot be mapped to any variable.

      The generated message (in Arabic) explains that the number of specified types cannot be greater than the number of variable names.

      Parameters:
      line - the source line number where the error occurred
      column - the source column number where the error occurred
      Returns:
      this method never returns normally; it always throws NaftahBugError
      Throws:
      NaftahBugError - always thrown to indicate a types-to-variables mismatch

    • newNaftahSettingConstantError

      public static NaftahBugError newNaftahSettingConstantError(String name)
      Creates a NaftahBugError indicating that an attempt was made to reassign a constant (final or otherwise immutable) variable.

      This overload simply delegates to newNaftahSettingConstantError(String, Throwable) with a null cause.

      The generated error message (written in Arabic) includes the name of the constant that was attempted to be reassigned.

      Parameters:
      name - the name of the constant variable being reassigned
      Returns:
      a new NaftahBugError describing the constant reassignment error
      Throws:
      NaftahBugError - this method always creates an error instance; intended to be thrown by the caller

    • newNaftahSettingConstantError

      public static NaftahBugError newNaftahSettingConstantError(String name, Throwable th)
      Creates a NaftahBugError indicating that an attempt was made to reassign a constant (final or otherwise immutable) variable, optionally wrapping the underlying cause.

      If a non-null Throwable is provided, an IllegalArgumentException will be created and chained with an IllegalAccessException whose message mirrors the original cause. This preserves the original error context while signaling that a constant value cannot be modified.

      The generated error message (in Arabic) includes the name of the constant that was attempted to be reassigned:

       "حدث خطأ أثناء إعادة تعيين القيمة الثابتة: '%s'. لا يمكن إعادة تعيين ثابت."
      Parameters:
      name - the name of the constant variable being reassigned
      th - an optional underlying cause; may be null
      Returns:
      a new NaftahBugError describing the constant reassignment error
      Throws:
      NaftahBugError - this method creates an error instance; intended to be thrown by the caller

    • newIllegalFieldAccessException

      public static IllegalAccessException newIllegalFieldAccessException(String fieldName)
      Creates an IllegalAccessException indicating that a reflective write to a constant (final/static) field was ignored by the JVM.

      This can happen when attempting to modify a field that the JVM treats as immutable, such as a final field, where the write is silently ignored without throwing an exception.

      Parameters:
      fieldName - the name of the field that was attempted to be modified
      Returns:
      an IllegalAccessException describing the failed reflective write

    • newNaftahTypeMismatchError

      public static NaftahBugError newNaftahTypeMismatchError(String name, String type, int line, int column)
      Creates a NaftahBugError representing a type-mismatch error with source location information.

      This overload is used when the type mismatch can be associated with a specific position in the source code (line and column).

      The generated error message is localized (Arabic) and indicates that the provided value does not match the expected type.

      Parameters:
      name - the name of the value, variable, or parameter that caused the mismatch
      type - the expected type description (usually produced by the Naftah type system)
      line - the source line number where the error occurred, or -1 if unknown
      column - the character position in the line where the error occurred, or -1 if unknown
      Returns:
      a NaftahBugError describing the type mismatch

    • newIllegalArgumentException

      public static IllegalArgumentException newIllegalArgumentException(Object object)
      Creates an IllegalArgumentException indicating that a value has an unsupported runtime type.

      The generated error message is localized (Arabic) and includes the fully qualified class name of the offending object when available. If the provided object is null, the message explicitly reports null as the unsupported type.

      This exception does not include source location information and is intended for internal runtime type validation failures.

      Parameters:
      object - the object whose runtime type is unsupported; may be null
      Returns:
      an IllegalArgumentException describing the unsupported type

    • newIllegalArgumentException

      public static IllegalArgumentException newIllegalArgumentException(Object object, Object object1)
      Creates an IllegalArgumentException indicating that a combination of values has unsupported or incompatible runtime types.

      The generated error message is localized (Arabic) and includes the fully qualified class names of both offending objects when available. If either object is null, null is reported explicitly for that position in the message.

      This overload is typically used when validating operations involving two operands whose runtime types are unsupported or incompatible in combination.

      This exception does not include source location information and is intended for internal runtime type validation failures.

      Parameters:
      object - the first object with an unsupported runtime type; may be null
      object1 - the second object with an unsupported runtime type; may be null
      Returns:
      an IllegalArgumentException describing the unsupported types