Interface MathLink

All Known Subinterfaces:
KernelLink, LoopbackLink

public interface MathLink
MathLink is the low-level interface that is the root of all link objects in J/Link. The methods in MathLink correspond roughly to a subset of those in the C-language MathLink API. Most programmers will deal instead with objects of type KernelLink, a higher-level interface that extends MathLink and incorporates the assumption that the program on the other side of the link is a Mathematica kernel.

You create objects of type MathLink via the MathLinkFactory.createLink() method. Again, though, most programmers will use KernelLink instead of MathLink.

Most MathLink methods throw a MathLinkException if a link-related error occurs. Examples would be calling endPacket() before sending a complete expression, or calling getFunction() when an integer is waiting on the link.

For additional information about these methods, see the J/Link User Guide, and also the MathLink documentation in the Mathematica book. Most of these methods are substantially similar, if not identical, to their C counterparts as documented in the book.

See Also:
KernelLink, MathLinkFactory
  • Field Summary

    Fields 
    Modifier and Type Field Description
    static int BEGINDLGPKT
    Constant returned by nextPacket.
    static int CALLPKT
    Constant returned by nextPacket.
    static int DISPLAYENDPKT
    Constant returned by nextPacket.
    static int DISPLAYPKT
    Constant returned by nextPacket.
    static int ENDDLGPKT
    Constant returned by nextPacket.
    static int ENTEREXPRPKT
    Constant returned by nextPacket.
    static int ENTERTEXTPKT
    Constant returned by nextPacket.
    static int EVALUATEPKT
    Constant returned by nextPacket.
    static int EXPRESSIONPKT  
    static int FEPKT  
    static int FIRSTUSERPKT  
    static int ILLEGALPKT  
    static int INPUTNAMEPKT
    Constant returned by nextPacket.
    static int INPUTPKT
    Constant returned by nextPacket.
    static int INPUTSTRPKT
    Constant returned by nextPacket.
    static int LASTUSERPKT  
    static int MENUPKT
    Constant returned by nextPacket.
    static int MESSAGEPKT
    Constant returned by nextPacket.
    static int MLABORTMESSAGE
    Used in putMessage() to cause the current Mathematica evaluation to be aborted.
    static int MLAUTHENTICATEFAILURE
    Low-level message type that will be detected by a messagehandler function if the kernel fails to start because of an authentication error (e.g., incorrect password file).
    static int MLE_ARRAY_TOO_SHALLOW  
    static int MLE_BAD_COMPLEX  
    static int MLE_CONNECT_TIMEOUT  
    static int MLE_CREATION_FAILED  
    static int MLE_FIRST_USER_EXCEPTION  
    static int MLE_LINK_IS_NULL  
    static int MLE_NON_ML_ERROR  
    static int MLE_OUT_OF_MEMORY  
    static int MLE_WRAPPED_EXCEPTION  
    static int MLEOK  
    static int MLEUSER  
    static int MLINTERRUPTMESSAGE  
    static int MLTERMINATEMESSAGE  
    static int MLTKERR  
    static int MLTKFUNC
    Constant for use in putNext() or returned by getNext() and getType().
    static int MLTKINT
    Constant for use in putNext() or returned by getNext() and getType().
    static int MLTKREAL
    Constant for use in putNext() or returned by getNext() and getType().
    static int MLTKSTR
    Constant for use in putNext() or returned by getNext() and getType().
    static int MLTKSYM
    Constant for use in putNext() or returned by getNext() and getType().
    static int OUTPUTNAMEPKT
    Constant returned by nextPacket.
    static int RESUMEPKT
    Constant returned by nextPacket.
    static int RETURNEXPRPKT
    Constant returned by nextPacket.
    static int RETURNPKT
    Constant returned by nextPacket.
    static int RETURNTEXTPKT
    Constant returned by nextPacket.
    static int SUSPENDPKT
    Constant returned by nextPacket.
    static int SYNTAXPKT
    Constant returned by nextPacket.
    static int TEXTPKT
    Constant returned by nextPacket.
    static int TYPE_BIGDECIMAL
    Constant for use in getArray().
    static int TYPE_BIGINTEGER
    Constant for use in getArray().
    static int TYPE_BOOLEAN
    Constant for use in getArray().
    static int TYPE_BYTE
    Constant for use in getArray().
    static int TYPE_CHAR
    Constant for use in getArray().
    static int TYPE_COMPLEX
    Constant for use in getArray().
    static int TYPE_DOUBLE
    Constant for use in getArray().
    static int TYPE_EXPR
    Constant for use in getArray().
    static int TYPE_FLOAT
    Constant for use in getArray().
    static int TYPE_INT
    Constant for use in getArray().
    static int TYPE_LONG
    Constant for use in getArray().
    static int TYPE_SHORT
    Constant for use in getArray().
    static int TYPE_STRING
    Constant for use in getArray().
  • Method Summary

    Modifier and Type Method Description
    void activate()
    Same as connect().
    boolean addMessageHandler​(java.lang.Class cls, java.lang.Object obj, java.lang.String methName)
    Specifies the Java method you want called as a message handler.
    int bytesToGet()
    Returns the number of bytes that remain to be read in the element that is currently being read in textual form.
    int bytesToPut()
    Gives the number of bytes that remain to be sent in the element that is currently being sent in textual form.
    int checkFunction​(java.lang.String f)
    Reads a function name and argument count and compares the function name with f.
    void checkFunctionWithArgCount​(java.lang.String f, int argCount)
    Reads a function name and argument count and compares the function name with f and the argument count with argCount.
    boolean clearError()
    Clears the link error condition, if possible.
    void close()
    Closes the link.
    void connect()
    Connects the link, if it has not already been connected.
    void connect​(long timeoutMillis)
    Connects the link, but waits at most timeoutMillis for a response from the other side.
    long createMark()
    Creates a mark at the current point in the incoming MathLink data stream.
    void destroyMark​(long mark)
    Destroys a mark.
    void endPacket()
    Call it when you are finished writing the contents of a single packet.
    int error()
    Gives the code corresponding to the current error state of the link.
    java.lang.String errorMessage()
    Gives a textual message describing the current error.
    void flush()
    Immediately transmits any data buffered for sending over the link.
    int getArgCount()
    Reads the argument count of an expression being read manually.
    java.lang.Object getArray​(int type, int depth)
    Reads an array of the specified type and depth.
    java.lang.Object getArray​(int type, int depth, java.lang.String[] heads)
    Reads an array of the specified type and depth and records the heads at each level.
    boolean getBoolean()
    Reads the Mathematica symbols True or False as a boolean.
    boolean[] getBooleanArray1()
    Reads a list as a one-dimensional array of booleans.
    boolean[][] getBooleanArray2()
    Reads an array as a two-dimensional array of booleans.
    byte[] getByteArray1()
    Reads a list or array as a one-dimensional array of bytes.
    byte[][] getByteArray2()
    Reads an array as a two-dimensional array of bytes.
    byte[] getByteString​(int missing)
    Reads a Mathematica string as an array of bytes.
    char[] getCharArray1()
    Reads a list or array as a one-dimensional array of chars.
    char[][] getCharArray2()
    Reads an array as a two-dimensional array of chars.
    java.lang.Object getComplex()
    Reads a complex number.
    java.lang.Object[] getComplexArray1()
    Reads a list as a one-dimensional array of complex numbers.
    java.lang.Object[][] getComplexArray2()
    Reads a matrix as a two-dimensional array of complex numbers.
    java.lang.Class getComplexClass()
    Gives the Java class that you have specified to map to Mathematica's Complex numbers.
    byte[] getData​(int len)
    Gets a specified number of bytes in the textual form of the expression currently being read.
    double getDouble()
    Reads a Mathematica real number or integer as a double.
    double[] getDoubleArray1()
    Reads a list or array as a one-dimensional array of doubles.
    double[][] getDoubleArray2()
    Reads an array as a two-dimensional array of doubles.
    Expr getExpr()
    Reads an expression from the link and creates an Expr from it.
    float[] getFloatArray1()
    Reads a list or array as a one-dimensional array of floats.
    float[][] getFloatArray2()
    Reads an array as a two-dimensional array of floats.
    MLFunction getFunction()
    Reads a function name and argument count.
    int[] getIntArray1()
    Reads a list or array as a one-dimensional array of ints.
    int[][] getIntArray2()
    Reads an array as a two-dimensional array of ints.
    int getInteger()
    Reads a Mathematica integer as an int.
    long[] getLongArray1()
    Reads a list as a one-dimensional array of longs.
    long[][] getLongArray2()
    Reads an array as a two-dimensional array of longs.
    long getLongInteger()
    Reads a Mathematica integer as a long.
    int getMessage()
    Deprecated. 
    int getNext()
    Gives the type of the next element in the expression currently being read.
    short[] getShortArray1()
    Reads a list or array as a one-dimensional array of shorts.
    short[][] getShortArray2()
    Reads an array as a two-dimensional array of shorts.
    java.lang.String getString()
    Reads a Mathematica character string.
    java.lang.String[] getStringArray1()
    Reads a list as a one-dimensional array of strings.
    java.lang.String[][] getStringArray2()
    Reads an array as a two-dimensional array of strings.
    java.lang.String getSymbol()
    Reads a Mathematica symbol as a string.
    int getType()
    Gives the type of the current element in the expression currently being read.
    boolean messageReady()
    Deprecated. 
    java.lang.String name()
    Gives the name of the link.
    void newPacket()
    Discards the current packet, if it has been partially read.
    int nextPacket()
    "Opens" the next packet arriving on the link.
    Expr peekExpr()
    Creates an Expr from the current expression, but does not drain it off the link.
    void put​(boolean b)
    Sends the boolean value as the Mathematica symbol True or False.
    void put​(double d)
    Sends a double value.
    void put​(int i)
    Sends an integer value.
    void put​(long i)
    Sends a long value.
    void put​(java.lang.Object obj)
    Sends an object, including strings and arrays.
    void put​(java.lang.Object obj, java.lang.String[] heads)
    Sends an array object.
    void putArgCount​(int argCount)
    Specifies the argument count for a composite expression being sent manually.
    void putByteString​(byte[] data)
    Sends an array of bytes to Mathematica as a string.
    void putData​(byte[] data)
    Used for sending elements in textual form.
    void putData​(byte[] data, int len)
    An alternative form of putData() that lets you specify how many bytes from the array should be sent, rather than just sending the whole thing.
    void putFunction​(java.lang.String f, int argCount)
    Sends a function name and argument count.
    void putMessage​(int msg)
    Sends a low-level MathLink message.
    void putNext​(int type)
    Identifies the type of data element that is to be sent.
    void putSize​(int size)
    Specifies the size in bytes of an element being sent in textual form.
    void putSymbol​(java.lang.String s)
    Sends a symbol name.
    boolean ready()
    Indicates whether the link has data waiting to be read.
    boolean removeMessageHandler​(java.lang.String methName)
    Removes a message handler you previously set up with addMessageHandler.
    void seekMark​(long mark)
    Resets the current position in the incoming MathLink data stream to an earlier point.
    boolean setComplexClass​(java.lang.Class cls)
    Specifies the class you want to map to Mathematica's Complex numbers.
    void setError​(int err)
    Sets the link's error state to the specified value.
    boolean setYieldFunction​(java.lang.Class cls, java.lang.Object obj, java.lang.String methName)
    Sets the Java method you want called as a yield function.
    void transferExpression​(MathLink source)
    Writes a complete expression from the link source to this link.
    void transferToEndOfLoopbackLink​(LoopbackLink source)
    Writes the entire contents of the LoopbackLink source to this link.
  • Field Details

  • Method Details

    • close

      void close()
      Closes the link. Always call close() on every link when you are done using it.
    • connect

      void connect() throws MathLinkException
      Connects the link, if it has not already been connected. There is a difference between opening a link (which is what the MathLinkFactory methods createLink() and createKernelLink() do) and connecting it, which verifies that it is alive and ready for data transfer.

      All the methods that read from the link will connect it if necessary. The connect() method lets you deliberately control the point in the program where the connection occurs, without having to read anything.

      Throws:
      MathLinkException
    • connect

      void connect​(long timeoutMillis) throws MathLinkException
      Connects the link, but waits at most timeoutMillis for a response from the other side. If the timeout passes, a MathLinkException is thrown. This is a handy way to prevent your thread from hanging indefinitely if there is a problem in connecting. Such problems are not hard to generate--for example, if the user launches a process other than a Mathematica kernel in their arguments to MathLinkFactory.createKernelLink(), the Java side will likely hang at the stage of connecting. If the timeout passes and an exception is thrown, the link cannot be salvaged and should be closed. Make sure you give adequate time for the kernel to launch.
      Parameters:
      timeoutMillis - the number of milliseconds to wait
      Throws:
      MathLinkException
      See Also:
      connect()
    • activate

      void activate() throws MathLinkException
      Same as connect().
      Throws:
      MathLinkException
      See Also:
      connect()
    • name

      java.lang.String name() throws MathLinkException
      Gives the name of the link. For typical links, the name of a listen-mode link can be used by the other side to connect to.
      Throws:
      MathLinkException
    • newPacket

      void newPacket()
      Discards the current packet, if it has been partially read. Has no effect if the previous packet was fully read.

      This is a useful cleanup function. You can call it when you are finished examining the contents of a packet that was opened with nextPacket() or waitForAnswer(), whether you have read the entire packet contents or not. You can be sure that the link is then in a state where you are ready to read the next packet.

      It is also frequently used in a catch block for a MathLinkException, to clear off any unread data in a packet before returning to the normal program flow.

      See Also:
      nextPacket()
    • nextPacket

      int nextPacket() throws MathLinkException
      "Opens" the next packet arriving on the link. It is an error to call nextPacket() while the current packet has unread data; use newPacket() to discard the current packet first.

      Most programmers will use this method rarely, if ever. J/Link provides higher-level functions in the KernelLink interface that hide these low-level details of the packet loop.

      Returns:
      the packet type (e.g., RETURNPKT, TEXTPKT).
      Throws:
      MathLinkException
      See Also:
      newPacket()
    • endPacket

      void endPacket() throws MathLinkException
      Call it when you are finished writing the contents of a single packet.

      Calling endPacket() is not strictly necessary, but it is good style, and it allows J/Link to immediately generate a MathLinkException if you are not actually finished with writing the data you promised to send.

      Throws:
      MathLinkException
    • error

      int error()
      Gives the code corresponding to the current error state of the link.
      Returns:
      the error code; will be MLEOK if no error.
      See Also:
      errorMessage(), clearError()
    • clearError

      boolean clearError()
      Clears the link error condition, if possible. After an error has occurred, and a MathLinkException has been caught, you must call clearError() before doing anything else with the link.
      Returns:
      true, if the error state was cleared; false, if the error could not be cleared. If false, you must close the link.
    • errorMessage

      java.lang.String errorMessage()
      Gives a textual message describing the current error.
      Returns:
      the error message
      See Also:
      error()
    • setError

      void setError​(int err)
      Sets the link's error state to the specified value. Afterwards, error() will return this value. Very few programmers will have any need for this method.
      Parameters:
      err - the error code
    • ready

      boolean ready() throws MathLinkException
      Indicates whether the link has data waiting to be read. In other words, it tells whether the next call that reads data will block or not.
      Returns:
      true, if data is waiting; false otherwise
      Throws:
      MathLinkException
    • flush

      void flush() throws MathLinkException
      Immediately transmits any data buffered for sending over the link.

      Any calls that read from the link will flush it, so you only need to call flush() manually if you want to make sure data is sent right away even though you are not reading from the link immediately. Calls to ready() will not flush the link, so if you are sending something and then polling ready() waiting for the result to arrive (as opposed to just calling nextPacket() or waitForAnswer()), you must call flush to ensure that the data is sent.

      Throws:
      MathLinkException
    • getNext

      int getNext() throws MathLinkException
      Gives the type of the next element in the expression currently being read.

      To check the type of a partially read element without advancing to the next element, use getType().

      Returns:
      one of MLTKINT, MLTKREAL, MLTKSTR, MLTKSYM, MLTKFUNC
      Throws:
      MathLinkException
    • getType

      int getType() throws MathLinkException
      Gives the type of the current element in the expression currently being read.

      Unlike getNext(), getType() will not advance to the next element if the current element has only been partially read.

      Returns:
      one of MLTKINT, MLTKREAL, MLTKSTR, MLTKSYM, MLTKFUNC
      Throws:
      MathLinkException
      See Also:
      getNext()
    • putNext

      void putNext​(int type) throws MathLinkException
      Identifies the type of data element that is to be sent.

      putNext() is rarely needed. The two most likely uses are to put expressions whose heads are not mere symbols (e.g., Derivative[2][f]) or to put data in textual form. Calls to putNext() must be followed by putSize() and putData(), or by putArgCount() for the MLTKFUNC type. Here is how you could send Derivative[2][f]:

       ml.putNext(MathLink.MLTKFUNC);  // The func we are putting has head Derivative[2], arg f
       ml.putArgCount(1);  // this 1 is for the 'f'
       ml.putNext(MathLink.MLTKFUNC);  // The func we are putting has head Derivative, arg 2
       ml.putArgCount(1);  // this 1 is for the '2'
       ml.putSymbol("Derivative");
       ml.put(2);
       ml.putSymbol("f");
      Parameters:
      type - one of MLTKINT, MLTKREAL, MLTKSTR, MLTKSYM, MLTKFUNC
      Throws:
      MathLinkException
      See Also:
      putSize(int), putData(byte[]), putArgCount(int)
    • getArgCount

      int getArgCount() throws MathLinkException
      Reads the argument count of an expression being read manually.

      This method can be used after getNext() or getType() returns the value MLTKFUNC. The argument count is always followed by the head of the expression. The head is followed by the arguments; the argument count tells how many there will be.

      Returns:
      the number of arguments in the expression being read
      Throws:
      MathLinkException
      See Also:
      getNext(), getType()
    • putArgCount

      void putArgCount​(int argCount) throws MathLinkException
      Specifies the argument count for a composite expression being sent manually.

      Use it after a call to putNext() with the MLTKFUNC type.

      Parameters:
      argCount - the number of aruments in the expression being sent
      Throws:
      MathLinkException
      See Also:
      putNext(int)
    • putSize

      void putSize​(int size) throws MathLinkException
      Specifies the size in bytes of an element being sent in textual form.

      A typical sequence would be putNext(), followed by putSize(), then putData().

      Parameters:
      size - the size of the data, in bytes, that will be written with the following putData()
      Throws:
      MathLinkException
      See Also:
      putData(byte[]), putNext(int)
    • bytesToPut

      int bytesToPut() throws MathLinkException
      Gives the number of bytes that remain to be sent in the element that is currently being sent in textual form.

      After you have called putSize(), the link knows how many bytes you have promised to send. This method lets you determine how many you still need to send, in the unlikely event that you lose track after a series of putData() calls.

      Returns:
      the number of bytes that remain to be sent
      Throws:
      MathLinkException
      See Also:
      putSize(int), putData(byte[])
    • bytesToGet

      int bytesToGet() throws MathLinkException
      Returns the number of bytes that remain to be read in the element that is currently being read in textual form.

      Lets you keep track of your progress reading an element through a series of getData() calls.

      Returns:
      the number of bytes that remain to be read in the current element
      Throws:
      MathLinkException
      MathLinkException
      See Also:
      getData(int)
    • putData

      void putData​(byte[] data) throws MathLinkException
      Used for sending elements in textual form. After calling putNext() and putSize(), a series of putData() calls are used to send the actual data.

      The so-called "textual" means of sending data is rarely used. Its main use is to allow a very large string to be sent, where the string data is not held in a single String object. The most important use of this technique in the C-language MathLink API was to send integers and reals that were too large to fit into an int or double. This use is unnecessary in J/Link, since Java has BigInteger and BigDecimal classes, and these objects can be sent directly with put().

      Parameters:
      data - the textual representation of the data
      Throws:
      MathLinkException
      See Also:
      putNext(int), putSize(int)
    • putData

      void putData​(byte[] data, int len) throws MathLinkException
      An alternative form of putData() that lets you specify how many bytes from the array should be sent, rather than just sending the whole thing.
      Parameters:
      data -
      len -
      Throws:
      MathLinkException
      See Also:
      putData(byte[])
    • getData

      byte[] getData​(int len) throws MathLinkException
      Gets a specified number of bytes in the textual form of the expression currently being read. The returned array will have a length of at most len.

      You can use bytesToGet() to determine if more getData() calls are needed to completely read the element.

      Parameters:
      len - the maximum number of bytes to read
      Returns:
      the data read
      Throws:
      MathLinkException
      See Also:
      bytesToGet(), getNext(), getType()
    • getString

      java.lang.String getString() throws MathLinkException
      Reads a Mathematica character string.

      Because both Java and Mathematica strings are in Unicode, the read string is an exact match to its Mathematica representation.

      Returns:
      the string that was read
      Throws:
      MathLinkException
    • getByteString

      byte[] getByteString​(int missing) throws MathLinkException
      Reads a Mathematica string as an array of bytes.

      In contrast with getString(), this method strips the incoming (16-bit Unicode) character data into single-byte representation. Characters that cannot be represented faithfully in single-byte form are replaced by the byte specified by the missing parameter. This method is primarily useful if you know the incoming data contains only ASCII characters and you want the data in the form of a byte array.

      Parameters:
      missing - the byte to replace non-ASCII characters with
      Returns:
      the data that was read
      Throws:
      MathLinkException
      See Also:
      getString()
    • putByteString

      void putByteString​(byte[] data) throws MathLinkException
      Sends an array of bytes to Mathematica as a string.

      Use this instead of put() if you have string data in the form of a byte array. In the C-language MathLink API, MLPutByteString was useful because the more obviously-named MLPutString required a specially-encoded string. Because Java strings and Mathematica strings are both Unicode, put() works in J/Link without requiring special encoding. Thus, putByteString() has little use.

      Parameters:
      data - the string data to send
      Throws:
      MathLinkException
      See Also:
      put(Object)
    • getSymbol

      java.lang.String getSymbol() throws MathLinkException
      Reads a Mathematica symbol as a string.

      Because Java strings and Mathematica symbols are in Unicode, the read string is an exact match to its Mathematica representation.

      Returns:
      the symbol
      Throws:
      MathLinkException
      See Also:
      getString()
    • putSymbol

      void putSymbol​(java.lang.String s) throws MathLinkException
      Sends a symbol name.

      Both Java strings and Mathematica symbols are in Unicode, so you can send symbols with the full Unicode character set.

      Parameters:
      s - the symbol name
      Throws:
      MathLinkException
    • getBoolean

      boolean getBoolean() throws MathLinkException
      Reads the Mathematica symbols True or False as a boolean. More precisely, it returns true if the symbol True is read, and false if False (or any other non-True symbol) is read. If you want to make sure that either True or False is on the link, don't use getBoolean(); instead, read the symbol with getSymbol() and test its value yourself.
      Returns:
      the boolean read
      Throws:
      MathLinkException
    • put

      void put​(boolean b) throws MathLinkException
      Sends the boolean value as the Mathematica symbol True or False.
      Parameters:
      b - the value to send
      Throws:
      MathLinkException
    • getInteger

      int getInteger() throws MathLinkException
      Reads a Mathematica integer as an int.
      Returns:
      the integer read
      Throws:
      MathLinkException
    • put

      void put​(int i) throws MathLinkException
      Sends an integer value.
      Parameters:
      i - the int to send
      Throws:
      MathLinkException
    • getLongInteger

      long getLongInteger() throws MathLinkException
      Reads a Mathematica integer as a long.
      Returns:
      the long that was read
      Throws:
      MathLinkException
    • put

      void put​(long i) throws MathLinkException
      Sends a long value.
      Parameters:
      i - the value to send
      Throws:
      MathLinkException
    • getDouble

      double getDouble() throws MathLinkException
      Reads a Mathematica real number or integer as a double.
      Returns:
      the double value read
      Throws:
      MathLinkException
    • put

      void put​(double d) throws MathLinkException
      Sends a double value.
      Parameters:
      d - the double to send
      Throws:
      MathLinkException
    • getBooleanArray1

      boolean[] getBooleanArray1() throws MathLinkException
      Reads a list as a one-dimensional array of booleans.

      The expression being read must be a list or other depth-1 expression of the symbols True and False. The "1" suffix in the method name indicates that the returned array has depth 1.

      The expression does not need to have head List. In other words, it could be List[False, True] or Foo[True, True]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not a depth-1 array of True and False
      See Also:
      getArray(int, int)
    • getBooleanArray2

      boolean[][] getBooleanArray2() throws MathLinkException
      Reads an array as a two-dimensional array of booleans.

      The expression being read must be a matrix of the symbols True and False. The "2" suffix in the method name indicates that the returned array has depth 2.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[True, False], List[True, True]] or Foo[Bar[True, False], Bar[True, True]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not a 2-deep array of True and False
      See Also:
      getArray(int, int)
    • getByteArray1

      byte[] getByteArray1() throws MathLinkException
      Reads a list or array as a one-dimensional array of bytes.

      The expression being read must be a list or deeper array of integers. Values outside the range of a byte are converted via casting. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of integers
      See Also:
      getArray(int, int)
    • getByteArray2

      byte[][] getByteArray2() throws MathLinkException
      Reads an array as a two-dimensional array of bytes.

      The expression being read must be a matrix or deeper array of integers. Values outside the range of a byte are converted via casting. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of integers
      See Also:
      getArray(int, int)
    • getCharArray1

      char[] getCharArray1() throws MathLinkException
      Reads a list or array as a one-dimensional array of chars.

      The expression being read must be a list or deeper array of integers. Values outside the range of a char are converted via casting. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of integers
      See Also:
      getArray(int, int)
    • getCharArray2

      char[][] getCharArray2() throws MathLinkException
      Reads an array as a two-dimensional array of chars.

      The expression being read must be a matrix or deeper array of integers. Values outside the range of a char are converted via casting. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of integers
      See Also:
      getArray(int, int)
    • getShortArray1

      short[] getShortArray1() throws MathLinkException
      Reads a list or array as a one-dimensional array of shorts.

      The expression being read must be a list or deeper array of integers. Values outside the range of a short are converted via casting. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of integers
      See Also:
      getArray(int, int)
    • getShortArray2

      short[][] getShortArray2() throws MathLinkException
      Reads an array as a two-dimensional array of shorts.

      The expression being read must be a matrix or deeper array of integers. Values outside the range of a short are converted via casting. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of integers
      See Also:
      getArray(int, int)
    • getIntArray1

      int[] getIntArray1() throws MathLinkException
      Reads a list or array as a one-dimensional array of ints.

      The expression being read must be a list or deeper array of integers. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of integers
      See Also:
      getArray(int, int)
    • getIntArray2

      int[][] getIntArray2() throws MathLinkException
      Reads an array as a two-dimensional array of ints.

      The expression being read must be a matrix or deeper array of integers. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of integers
      See Also:
      getArray(int, int)
    • getLongArray1

      long[] getLongArray1() throws MathLinkException
      Reads a list as a one-dimensional array of longs.

      The expression being read must be a list or other depth-1 expression of integers. The "1" suffix in the method name indicates that the returned array has depth 1.

      The expression does not need to have head List. In other words, it could be List[1, 2] or Foo[1, 2]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not a depth-1 array of integers
      See Also:
      getArray(int, int)
    • getLongArray2

      long[][] getLongArray2() throws MathLinkException
      Reads an array as a two-dimensional array of longs.

      The expression being read must be a matrix of integers. The "2" suffix in the method name indicates that the returned array has depth 2.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1, 2], List[3, 4]] or Foo[Bar[1, 2], Bar[3, 4]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not a depth-2 array of integers
      See Also:
      getArray(int, int)
    • getFloatArray1

      float[] getFloatArray1() throws MathLinkException
      Reads a list or array as a one-dimensional array of floats.

      The expression being read must be a list or deeper array of real numbers or integers. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1., 2.], List[3., 4.]] or Foo[Bar[1., 2.], Bar[3., 4.]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of reals or integers
      See Also:
      getArray(int, int)
    • getFloatArray2

      float[][] getFloatArray2() throws MathLinkException
      Reads an array as a two-dimensional array of floats.

      The expression being read must be a matrix or deeper array of real numbers or integers. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1., 2.], List[3., 4.]] or Foo[Bar[1., 2.], Bar[3., 4.]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an of array reals or integers
      See Also:
      getArray(int, int)
    • getDoubleArray1

      double[] getDoubleArray1() throws MathLinkException
      Reads a list or array as a one-dimensional array of doubles.

      The expression being read must be a list or deeper array of real numbers or integers. The "1" suffix in the method name indicates that the returned array has depth 1. If the arriving expression has depth greater than 1 (e.g., it is a matrix), it will be flattened to a 1-dimensional array.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1., 2.], List[3., 4.]] or Foo[Bar[1., 2.], Bar[3., 4.]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of reals or integers
      See Also:
      getArray(int, int)
    • getDoubleArray2

      double[][] getDoubleArray2() throws MathLinkException
      Reads an array as a two-dimensional array of doubles.

      The expression being read must be a matrix or deeper array of real numbers or integers. The "2" suffix in the method name indicates that the returned array has depth 2. If the arriving expression has depth greater than 2, it will be flattened to a 2-dimensional array. If the arriving expression has a depth less than 2 (i.e., it is a flat list), a MathLinkException will be thrown.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1., 2.], List[3., 4.]] or Foo[Bar[1., 2.], Bar[3., 4.]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not an array of reals or integers
      See Also:
      getArray(int, int)
    • getStringArray1

      java.lang.String[] getStringArray1() throws MathLinkException
      Reads a list as a one-dimensional array of strings.

      The expression being read must be a list or other depth-1 expression of strings or symbols. The "1" suffix in the method name indicates that the returned array has depth 1.

      The expression does not need to have head List. In other words, it could be List["A", "B"] or Foo["A", "B"]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not a depth-1 array of strings or symbols
      See Also:
      getArray(int, int)
    • getStringArray2

      java.lang.String[][] getStringArray2() throws MathLinkException
      Reads an array as a two-dimensional array of strings.

      The expression being read must be a matrix of strings or symbols. The "2" suffix in the method name indicates that the returned array has depth 2.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List["A", "B"], List["C", D"]] or Foo[Bar["A", "B"], Bar["C", "D"]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read
      Throws:
      MathLinkException - if the incoming expression is not a matrix of strings or symbols
      See Also:
      getArray(int, int)
    • getComplexArray1

      java.lang.Object[] getComplexArray1() throws MathLinkException
      Reads a list as a one-dimensional array of complex numbers.

      The expression being read must be a list or other depth-1 expression of Complex. The "1" suffix in the method name indicates that the returned array has depth 1.

      This method will read the expression, but return null, if no Java class has yet been established to use for complex numbers by calling setComplexClass.

      The expression does not need to have head List. In other words, it could be List[1+I, 2-I] or Foo[1+I, 2-I]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read, or null if no Java class has been declared for complex numbers via setComplexClass()
      Throws:
      MathLinkException - if the incoming expression is not a depth-1 array of Complex
      See Also:
      setComplexClass(Class), getArray(int, int)
    • getComplexArray2

      java.lang.Object[][] getComplexArray2() throws MathLinkException
      Reads a matrix as a two-dimensional array of complex numbers.

      The expression being read must be a matrix of Complex. The "2" suffix in the method name indicates that the returned array has depth 2.

      The expression does not need to have head List. It can have any heads, at any depth. In other words, it could be List[List[1+I, 2-I], List[3+I, 4-I]] or Foo[Bar[1+I, 2-I], Bar[3+I, 4-I]]. The information about the heads is lost; if you need this information you will need to either use getArray(int, int, String[]) or read the expression as an Expr and examine it using the Expr methods.

      Returns:
      the array read, or null if no Java class has been declared for complex numbers via setComplexClass()
      Throws:
      MathLinkException - if the incoming expression is not a matrix of Complex
      See Also:
      setComplexClass(Class), getArray(int, int)
    • getArray

      java.lang.Object getArray​(int type, int depth) throws MathLinkException
      Reads an array of the specified type and depth.

      The getXXXArrayN methods are all just convenience methods that call this method. Use this method instead when you want to read an array of dimensionality deeper than 2. Cast the result of this method to the desired array type, as in:

           int[][][] result = (int[][][]) ml.getArray(TYPE_INT, 3); 
      For the types TYPE_BYTE, TYPE_CHAR, TYPE_SHORT, TYPE_INT, TYPE_FLOAT, and TYPE_DOUBLE, if the expression has depth greater than depth, it will be flattened to a Java array of dimension depth. If the expression has a depth less than depth, a MathLinkException will be thrown.

      The maximum depth supported is 5.

      The expression does not need to have head List. It can have any heads, at any depth, and the heads do not have to agree at each depth, meaning that you could read the expression {foo[1, 2], bar[3, 4]} as an int[][]. The information about the heads is lost; if you need this information you can use the alternative signature getArray(int type, int depth, String[] heads), or read the expression as an Expr and examine it using the Expr methods.

      Parameters:
      type - The desired type for the returned array. Must be one of TYPE_BOOLEAN, TYPE_BYTE, TYPE_CHAR, TYPE_SHORT, TYPE_INT, TYPE_LONG, TYPE_FLOAT, TYPE_DOUBLE, TYPE_STRING, TYPE_BIGINTEGER, TYPE_BIGDECIMAL, TYPE_EXPR, or TYPE_COMPLEX.
      depth - the depth of the returned array
      Returns:
      the array read, or null if type is TYPE_COMPLEX and no Java class has been declared for complex numbers via setComplexClass()
      Throws:
      MathLinkException - if the incoming expression is not an array of the requested type or is not as deep as requested
      MathLinkException
      See Also:
      getArray(int, int, String[])
    • getArray

      java.lang.Object getArray​(int type, int depth, java.lang.String[] heads) throws MathLinkException
      Reads an array of the specified type and depth and records the heads at each level.

      Identical to getArray(int type, int depth), except that this form fills a String array with the heads of the expression found at each level. To use this method, allocate a String array of length 'depth' and pass it in. For example:

       // Assume that the expression {foo[1, 2], foo[3, 4]} is waiting on the link.
       String[] heads = new String[2];
       int[][] intArray2D = (int[][]) ml.getArray(MathLink.TYPE_INT, 2, heads);
       // Now heads[0] is "List" and heads[1] is "foo".
      This method does not enforce a requirement that the heads be identical across a level. If the expression looks like {foo[1, 2], bar[3, 4]} then the heads array would become {"List", "foo"}, ignoring the fact that foo was not the head of every subexpression at level 1. In other words, if heads[i] is "foo", then it is only guaranteed that some expression at level i had head foo, not that all of them did. If you want to be absolutely sure about the heads of every subpart, read the expression as an Expr and use the Expr methods to inspect it.
      Parameters:
      type - The desired type for the returned array. Must be one of TYPE_BOOLEAN, TYPE_BYTE, TYPE_CHAR, TYPE_SHORT, TYPE_INT, TYPE_LONG, TYPE_FLOAT, TYPE_DOUBLE, TYPE_STRING, TYPE_BIGINTEGER, TYPE_BIGDECIMAL, TYPE_EXPR, or TYPE_COMPLEX.
      depth - the depth of the returned array
      heads - an array of length 'depth' that will be filled with the heads at each level
      Returns:
      the array read, or null if type is TYPE_COMPLEX and no Java class has been declared for complex numbers via setComplexClass()
      Throws:
      MathLinkException - if the incoming expression is not an array of the requested type, or is not as deep as requested
      Since:
      2.0
      See Also:
      getArray(int, int)
    • getFunction

      MLFunction getFunction() throws MathLinkException
      Reads a function name and argument count.
      Returns:
      an object describing the head and argument count of the function
      Throws:
      MathLinkException
    • putFunction

      void putFunction​(java.lang.String f, int argCount) throws MathLinkException
      Sends a function name and argument count.

      Follow this with calls to put the arguments.

      Parameters:
      f - the function name
      argCount - the number of arguments to follow
      Throws:
      MathLinkException
    • checkFunction

      int checkFunction​(java.lang.String f) throws MathLinkException
      Reads a function name and argument count and compares the function name with f. If they do not match, a MathLinkException is thrown.

      Similar to getFunction() in that it reads the name and argument count off the link. Use it in situations where you want an error to occur if the function is not what you expect.

      Parameters:
      f - the function name that you are expecting
      Returns:
      the argument count
      Throws:
      MathLinkException - if the current expression is not a function, or if it does not have the specified name
      See Also:
      checkFunctionWithArgCount(String, int)
    • checkFunctionWithArgCount

      void checkFunctionWithArgCount​(java.lang.String f, int argCount) throws MathLinkException
      Reads a function name and argument count and compares the function name with f and the argument count with argCount. If they do not match, a MathLinkException is thrown.

      Similar to getFunction() in that it reads the name and argument count off the link. Use it in situations where you want an error to occur if the function is not what you expect.

      Parameters:
      f - the function name that you are expecting
      argCount - the argument count that you are expecting
      Throws:
      MathLinkException - if the current expression is not a function, or if it does not have the specified name
      See Also:
      checkFunction(String)
    • getComplex

      java.lang.Object getComplex() throws MathLinkException
      Reads a complex number. This can be an integer, real, or a Mathematica expression with head Complex. You must first specify a Java class for complex numbers using setComplexClass().

      This method will read the number, but return null, if no Java class has yet been established to use for complex numbers.

      Returns:
      an object of the class you have specified to map to Mathematica Complex numbers, or null if you have not specified any class (using setComplexClass()).
      Throws:
      MathLinkException - if the current expression is not an integer, real, or Mathematica Complex.
      See Also:
      setComplexClass(Class)
    • transferExpression

      void transferExpression​(MathLink source) throws MathLinkException
      Writes a complete expression from the link source to this link.
      Parameters:
      source - the link to read from
      Throws:
      MathLinkException
      See Also:
      transferToEndOfLoopbackLink(LoopbackLink)
    • transferToEndOfLoopbackLink

      void transferToEndOfLoopbackLink​(LoopbackLink source) throws MathLinkException
      Writes the entire contents of the LoopbackLink source to this link.
      Parameters:
      source - the LoopbackLink to read from
      Throws:
      MathLinkException
      See Also:
      transferExpression(MathLink)
    • getExpr

      Expr getExpr() throws MathLinkException
      Reads an expression from the link and creates an Expr from it.

      The returned Expr can be examined and manipulated later.

      Returns:
      the Expr read
      Throws:
      MathLinkException
      See Also:
      peekExpr()
    • peekExpr

      Expr peekExpr() throws MathLinkException
      Creates an Expr from the current expression, but does not drain it off the link.

      Like getExpr(), but peekExpr() does not actually remove anything from the link. In other words, it leaves the link in the same state it was in before peekExpr() was called.

      Returns:
      the Expr read
      Throws:
      MathLinkException
      See Also:
      getExpr()
    • getMessage

      int getMessage() throws MathLinkException
      Deprecated.
      Reads a low-level MathLink message.

      This method no longer functions in J/Link 2.0. You must use addMessageHandler() if you want to be able to receive messages from Mathematica.

      Returns:
      the message read; will most likely be one of MLINTERRUPTMESSAGE or MLABORTMESSAGE
      Throws:
      MathLinkException
      See Also:
      addMessageHandler(Class, Object, String)
    • putMessage

      void putMessage​(int msg) throws MathLinkException
      Sends a low-level MathLink message.

      To abort a Mathematica computation, use putMessage(MLABORTMESSAGE). If a computation is successfully aborted, it will return the symbol $Aborted.

      Do not confuse this type of message, used mainly for communicating requests to interrupt or abort computations, with Mathematica warning messages, which are unrelated.

      Parameters:
      msg - the message to send; will be one of MLABORTMESSAGE or MLINTERRUPTMESSAGE. Most users will only be concerned with MLABORTMESSAGE.
      Throws:
      MathLinkException
    • messageReady

      boolean messageReady() throws MathLinkException
      Deprecated.
      Tells whether a low-level MathLink message has arrived.

      This method no longer functions in J/Link 2.0. You must use addMessageHandler() if you want to be able to receive messages from Mathematica.

      Returns:
      true if a message is waiting to be read with getMessage(); false otherwise
      Throws:
      MathLinkException
      See Also:
      addMessageHandler(Class, Object, String)
    • createMark

      long createMark() throws MathLinkException
      Creates a mark at the current point in the incoming MathLink data stream.

      Marks can returned to later, to re-read data. A common use is to create a mark, call some method for reading data, and if a MathLinkException is thrown, seek back to the mark and try a different method of reading the data.

      Make sure to always call destroyMark() on any marks you create. Failure to do so will cause a memory leak.

      Some of the usefulness of marks in the C-language MathLink API is obviated by J/Link's Expr class.

      Returns:
      the mark. You cannot do anything with this value except use it in seekMark() or destroyMark(); it has no meaning as a number.
      Throws:
      MathLinkException
      See Also:
      seekMark(long), destroyMark(long)
    • seekMark

      void seekMark​(long mark)
      Resets the current position in the incoming MathLink data stream to an earlier point.
      Parameters:
      mark - the mark, created by createMark(), that identifies the desired position to reset to
      See Also:
      createMark(), seekMark(long)
    • destroyMark

      void destroyMark​(long mark)
      Destroys a mark. Always call destroyMark() on any marks you create with createMark().
      Parameters:
      mark - the mark to destroy
    • put

      void put​(java.lang.Object obj) throws MathLinkException
      Sends an object, including strings and arrays.

      Only a limited set of Java objects can be usefully sent across a link with this method. These are objects whose "values" have a meaningful representation in Mathematica:

       null: sent as the symbol Null.
       strings: sent as Mathematica strings
       arrays: sent as lists of the appropriate dimensions
       Expr: sent as expressions
       Wrapper classes (e.g., Boolean, Integer, Float, etc.): sent as their values
       BigDecimal and BigInteger: sent as their values
       complex numbers: sent as Complex
      All other objects have no meaningful representation in Mathematica. For these objects, the relatively useless obj.toString() is sent. The put(Object) method in the KernelLink interface will put these objects "by reference".
      Parameters:
      obj - the object to put
      Throws:
      MathLinkException
    • put

      void put​(java.lang.Object obj, java.lang.String[] heads) throws MathLinkException
      Sends an array object. Unlike put(Object), this method lets you specify the heads you want for each dimension.
           int[][] a = {{1,2},{3,4}};
           // The following are equivalent, sending to Mathematica the matrix: {{1,2},{3,4}}
           ml.put(a);
           ml.put(a, null);
           ml.put(a, new String[] {"List", "List"});
      Parameters:
      obj - must be an array
      heads - the heads at each dimension
      Throws:
      MathLinkException
    • setComplexClass

      boolean setComplexClass​(java.lang.Class cls)
      Specifies the class you want to map to Mathematica's Complex numbers.

      After calling setComplexClass(), you can use getComplex() to read an incoming Complex and create an instance of your class, and you can use put() to send objects of your class to Mathematica as Complex.

      To be suitable, your class must have a public constructor of the form MyComplex(double re, double im), and it must have two public methods double re() and double im().

      Parameters:
      cls - the class to map to Mathematica Complex numbers
      Returns:
      true, if the class is a suitable choice, false otherwise
      See Also:
      getComplexClass(), getComplex()
    • getComplexClass

      java.lang.Class getComplexClass()
      Gives the Java class that you have specified to map to Mathematica's Complex numbers.

      You specify the class you want using setComplexClass().

      Returns:
      the class, or null if no class has yet been specified
      See Also:
      setComplexClass(Class)
    • setYieldFunction

      boolean setYieldFunction​(java.lang.Class cls, java.lang.Object obj, java.lang.String methName)
      Sets the Java method you want called as a yield function.

      The method must be public and its signature must be (V)Z (e.g., public boolean foo()). You can pass null for cls if obj is provided. If the method is static, pass null as obj.

      Yield functions are an advanced topic, and are discussed in greater detail in the User Guide. Few users will need to use one.

      Parameters:
      cls - the class in which the method resides
      obj - the object on which the method should be invoked (use null if the method is static)
      methName - the name of the method to invoke
      Returns:
      true, if the specified method is suitable (i.e., could be found, and has the correct signature); false otherwise
    • addMessageHandler

      boolean addMessageHandler​(java.lang.Class cls, java.lang.Object obj, java.lang.String methName)
      Specifies the Java method you want called as a message handler.

      Do not confuse this type of message, used mainly for communicating requests to interrupt or abort a computation, with Mathematica warning and error messages, which are unrelated.

      The method you specify will be added to the set that are called whenever a MathLink message is received by your Java program. The method must be public and its signature must be (II)V (e.g., public void foo(int msgType, int ignore)). You can pass null for cls if obj is provided. If the method is static, pass null for obj. The first argument passed to your function when it is called is the integer code giving the message type (e.g., MLABORTMESSAGE, MLINTERRUPTMESSAGE, etc.) The second argument is undocumented and should be ignored.

      Do not attempt to use the link from within your message handler function.

      You can set more than one message handler, hence the name "addMessageHandler".

      Message handlers are an advanced technique. Few programmers will need to use one.

      Parameters:
      cls - the class in which the method resides
      obj - the object on which the method should be invoked (use null if the method is static)
      methName - the name of the method to invoke
      Returns:
      true, if the specified method is suitable (i.e., could be found, and has the correct signature); false otherwise
      See Also:
      removeMessageHandler(String)
    • removeMessageHandler

      boolean removeMessageHandler​(java.lang.String methName)
      Removes a message handler you previously set up with addMessageHandler.

      Do not confuse this type of message, used mainly for communicating requests to interrupt or abort a computation, with Mathematica warning and error messages, which are unrelated.

      Message handlers are an advanced topic, and are discussed in greater detail in the User Guide. Few users will need to use one.

      Parameters:
      methName - the name of the method to remove
      Returns:
      true, if the specified method was previously set as a message handler; false otherwise
      See Also:
      addMessageHandler(Class, Object, String)