Class MathLinkException

  • All Implemented Interfaces:
    java.io.Serializable

    public class MathLinkException
    extends java.lang.Exception
    The exception thrown by methods in the MathLink and KernelLink interfaces when a link error occurs.

    MathLinkExceptions are only for errors that involve the low-level link itself. After you catch a MathLinkException, the first thing you should do is call clearError() to try to clear the error condition. If you do not, then the next MathLink or KernelLink method you call will throw an exception again.

    For programmers familiar with the C-language MathLink API, the throwing of a MathLinkException is equivalent to a C-language function returning a result code other than MLEOK.

    See Also:
    Serialized Form
    • Constructor Summary

      Constructors 
      Constructor Description
      MathLinkException​(int code)
      Creates a MathLinkException given a code.
      MathLinkException​(int code, java.lang.String msg)
      Creates a MathLinkException given a code and textual description.
      MathLinkException​(java.lang.Throwable e)
      Creates a MathLinkException by wrapping another type of exception.
      MathLinkException​(java.lang.Throwable e, java.lang.String extraMsg)
      Creates a MathLinkException by wrapping another type of exception.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Throwable getCause()
      Gives the other type of exception that this MathLinkException "wraps".
      int getErrCode()
      Gives the low-level MathLink error code describing the link error.
      java.lang.String getMessage()
      Gives the textual message describing the link error.
      java.lang.Throwable getWrappedException()
      Gives the other type of exception that this MathLinkException "wraps".
      java.lang.String toString()
      Gives a string representation of the exception suitable for display to a user.
      • Methods inherited from class java.lang.Throwable

        addSuppressed, fillInStackTrace, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • MathLinkException

        public MathLinkException​(int code,
                                 java.lang.String msg)
        Creates a MathLinkException given a code and textual description. Programmers will probably have no need to create their own MathLinkExceptions.
        Parameters:
        code - the integer error code
        msg - the descriptive message
      • MathLinkException

        public MathLinkException​(int code)
        Creates a MathLinkException given a code. Programmers will probably have no need to create their own MathLinkExceptions.
        Parameters:
        code - the integer error code
      • MathLinkException

        public MathLinkException​(java.lang.Throwable e)
        Creates a MathLinkException by wrapping another type of exception. Only advanced programmers writing their own implementations of the MathLink interface will need to be concerned with this.

        This technique allows exceptions thrown by special-purpose implementations of the MathLink interface to be received and treated like they were native MathLink errors. Thus, client code does not need to be rewritten to accommodate special exception types thrown by a special type of MathLink. As an example, this is used by the RMI implementation of MathLink (not part of current standard JLink package) to wrap java.rmi.RemoteExceptions thrown by the RMI protocol.

        Parameters:
        e - the exception to wrap
      • MathLinkException

        public MathLinkException​(java.lang.Throwable e,
                                 java.lang.String extraMsg)
        Creates a MathLinkException by wrapping another type of exception. Only advanced programmers writing their own implementations of the MathLink interface will need to be concerned with this.

        This technique allows exceptions thrown by special-purpose implementations of the MathLink interface to be received and treated like they were native MathLink errors. Thus, client code does not need to be rewritten to accommodate special exception types thrown by a special type of MathLink. As an example, this is used by the RMI implementation of MathLink (not part of current standard JLink package) to wrap java.rmi.RemoteExceptions thrown by the RMI protocol.

        Parameters:
        e - the exception to wrap
        extraMsg - extra textual information you want included in the output of getMessage(), above and beyond the default of toString() of the wrapped exception.
    • Method Detail

      • getErrCode

        public int getErrCode()
        Gives the low-level MathLink error code describing the link error.
        Returns:
        the integer error code
        See Also:
        toString(), getMessage()
      • getMessage

        public java.lang.String getMessage()
        Gives the textual message describing the link error.
        Overrides:
        getMessage in class java.lang.Throwable
        See Also:
        toString()
      • getWrappedException

        public java.lang.Throwable getWrappedException()
        Gives the other type of exception that this MathLinkException "wraps".

        Some MathLinkExceptions are not "native" MathLink errors, but rather special exceptions thrown by special-purpose implementations of the MathLink interface. To allow these exceptions to be received and treated like they were native MathLink errors, yet retain their full type information, a MathLinkException can be created that "wraps" another exception. Thus, client code does not need to be rewritten to accommodate special exception types. As an example, this thechnique is used by the RMI implementation of MathLink (not part of the current standard J/Link package) to wrap java.rmi.RemoteExceptions thrown by the RMI protocol.

        Returns:
        the wrapped exception, or null if this is a normal native MathLinkException
        See Also:
        getCause()
      • getCause

        public java.lang.Throwable getCause()
        Gives the other type of exception that this MathLinkException "wraps".

        Identical to the getWrappedException() method, but included to conform to the design pattern for "chained" exceptions introduced in Java 1.4.

        Overrides:
        getCause in class java.lang.Throwable
        Returns:
        the wrapped exception, or null if this is a normal native MathLinkException
        See Also:
        getWrappedException()
      • toString

        public java.lang.String toString()
        Gives a string representation of the exception suitable for display to a user. The information includes both the error code and the message.
        Overrides:
        toString in class java.lang.Throwable
        See Also:
        getMessage(), getErrCode()