com.wolfram.jlink
Class MathLinkException

java.lang.Object
  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by 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()


J/Link is Copyright (c) 1999-2008, Wolfram Research, Inc. All rights reserved.