package nxm.sys.lib;

/** Base class for all exceptions that are generated due to errors that occur in NeXtMidas
    processing. Early on this class had functionality not normally available in most Java exception
    classes, however since Java 1.4.0 that functionality has been added to all Java exceptions.
    Since NeXtMidas 2.3.0 this class is nearly identical to a {@link RuntimeException}, however
    it is recommended that all library and primitive writers use this class whenever applicable
    since additional functionality may be added in the future.

    @author  J. Czechowski IV / Neon Ngo
 */
public class MidasException extends RuntimeException {

  /** NOTE: this should be changed if the structure/fields of this class changes. */
  private static final long serialVersionUID = -3244543265220722377L;

  /** Details about the exception */
  private final String details;

  /** Construct a new MidasException. */
  public MidasException () { this(null,null,null); }

  /** Construct a MidasException with the specified detail message.
      @param msg A string containing the text of the message.
   */
  public MidasException (String msg) { this(msg,null,null); }

  /** Constructs a new exception that includes a message about the "root cause" exception that
      interfered with its normal operation, including a description message.
      @param msg      A string containing the text of the message.
      @param details  Details about the exception or null if none are available.
      @since NeXtMidas 2.5.0
   */
  public MidasException (String msg, String details) { this(msg,details,null); }

  /** Initialize a new instance with the specified source Throwable with no new detail message.
      @param cause The root cause of this exception.
   */
  public MidasException (Throwable cause) { this(null,null,cause); }

  /** Constructs a new exception that includes a message about the "root cause" exception that
      interfered with its normal operation, including a description message.
      @param msg   A string containing the text of the message.
      @param cause The root cause of this exception.
   */
  public MidasException (String msg, Throwable cause) { this(msg,null,cause); }

  /** Constructs a new exception that includes a message about the "root cause" exception that
      interfered with its normal operation, including a description message.
      @param msg      A string containing the text of the message.
      @param details  Details about the exception or null if none are available.
      @param cause    The root cause of this exception.
      @since NeXtMidas 2.5.0
   */
  public MidasException (String msg, String details, Throwable cause) {
    super(msg,cause);
    this.details = details;
  }

  /** Returns the exception that caused this exception. This method was added prior to the addition
      of the {@link #getCause()} method in Java 1.4.0. Since NeXtMidas 2.3.0 this method simply
      calls {@link #getCause()}.
      @return root exception
   */
  public final Throwable getRootCause () { return super.getCause(); }

  /** Gets details about the exception.
      @return Details about the exception or null if none are available.
      @since NeXtMidas 2.5.0
   */
  public final String getDetails () { return details; }

  /** Return a short description of this object. The result of this string will be dependent on
      whether this object was created with a detail message or a source exception.
      @return A string representation of this object.
   */
  public String toString () {
    String str = super.toString();

    if (getDetails()   != null) str += " (" + getDetails()   + ")";
    if (getRootCause() != null) str += " (" + getRootCause() + ")";

    return str;
  }
}
