com.wolfram.jlink
Class MathLinkException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.wolfram.jlink.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

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

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

fillInStackTrace, getLocalizedMessage, getStackTrace, 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()