Writing Java Programs That Use Mathematica

Introduction

What Is MathLink?

Overview of the Main J/Link Interfaces and Classes

Preamble

MathLink and KernelLink

MathLinkFactory

MathLinkException

    // C code
    if (!MLPutInteger(link, 42)) {
        // was error; print message and clean up.
    }

Expr

PacketListener

High-Level User Interface Classes

Sample Program

(Windows)
java -classpath .;..\..\JLink.jar SampleProgram -linkmode launch -linkname "c:\program files\wolfram research\mathematica\6.0\mathkernel.exe"

(Unix)
java -classpath .:../../JLink.jar SampleProgram -linkmode launch -linkname 'math -mathlink'

(Mac OS X from a terminal window)
java -classpath .:../../JLink.jar SampleProgram -linkmode launch -linkname '"/Applications/Mathematica.app/Contents/MacOS/MathKernel" -mathlink'

import com.wolfram.jlink.*;

public class SampleProgram {

    public static void main(String[] argv) {

        KernelLink ml = null;

        try {
            ml = MathLinkFactory.createKernelLink(argv);
        } catch (MathLinkException e) {
            System.out.println("Fatal error opening link: " + e.getMessage());
            return;
        }

        try {
            // Get rid of the initial InputNamePacket the kernel will send
            // when it is launched.
            ml.discardAnswer();

            ml.evaluate("<<MyPackage.m");
            ml.discardAnswer();

            ml.evaluate("2+2");
            ml.waitForAnswer();

            int result = ml.getInteger();
            System.out.println("2 + 2 = " + result);

            // Here's how to send the same input, but not as a string:
            ml.putFunction("EvaluatePacket", 1);
            ml.putFunction("Plus", 2);
            ml.put(3);
            ml.put(3);
            ml.endPacket();
            ml.waitForAnswer();
            result = ml.getInteger();
            System.out.println("3 + 3 = " + result);

            // If you want the result back as a string, use evaluateToInputForm
            // or evaluateToOutputForm. The second arg for either is the
            // requested page width for formatting the string. Pass 0 for
            // PageWidth->Infinity. These methods get the result in one
            // step--no need to call waitForAnswer.
            String strResult = ml.evaluateToOutputForm("4+4", 0);
            System.out.println("4 + 4 = " + strResult);

        } catch (MathLinkException e) {
            System.out.println("MathLinkException occurred: " + e.getMessage());
        } finally {
            ml.close();
        }
    }
}

Creating Links with MathLinkFactory

public static KernelLink createKernelLink(String cmdLine) throws MathLinkException
    
public static KernelLink createKernelLink(String[] argv) throws MathLinkException
    
. . . plus a few more of limited usefulness

KernelLink ml = MathLinkFactory.createKernelLink("-linkmode launch -linkname 'c:\\program files\\wolfram research\\mathematica\\6.0\\mathkernel'");

// Typical launch on Windows
KernelLink ml = MathLinkFactory.createKernelLink("-linkmode launch -linkname 'c:\\program files\\wolfram research\\mathematica\\mathkernel.exe'");

// Typical launch on Unix
KernelLink ml = MathLinkFactory.createKernelLink("-linkmode launch -linkname 'math -mathlink'");

// Typical launch on Mac OS X
KernelLink ml = MathLinkFactory.createKernelLink("-linkmode launch -linkname '\"/Applications/Mathematica.app/Contents/MacOS/MathKernel\" -mathlink'");

// Typical "listen" link on any platform:
KernelLink ml = MathLinkFactory.createKernelLink("-linkmode listen -linkname 1234 -linkprotocol tcp");

// Windows can use the default protocol for listen/connect links:
KernelLink ml = MathLinkFactory.createKernelLink("-linkmode listen -linkname foo");

// Typical launch on Windows:
String[] argv = {"-linkmode", "launch", "-linkname", "c:\\program files\\wolfram research\\mathematica\\6.0\\mathkernel"};

// Typical launch on UNIX:
String[] argv = {"-linkmode", "launch", "-linkname", "math -mathlink"};

// Typical launch on Mac OS X:
String[] argv = {"-linkmode", "launch", "-linkname", "\"/Applications/Mathematica.app/Contents/MacOS/MathKernel\" -mathlink"};

// Typical "listen" link on any platform:
String[] argv = {"-linkmode", "listen", "-linkname", "1234", "-linkprotocol", "tcp"};

// Windows can use the default protocol for listen/connect links:
String[] argv = {"-linkmode", "listen", "-linkname", "foo"};

KernelLink ml = null;
try {
    ml = MathLinkFactory.createKernelLink("-linkmode launch -linkname 'c:\\program files\\wolfram research\\mathematica\\6.0\\mathkernel'");
} catch (MathLinkException e) {
    // This is equivalent to MLOpen returning NULL in a C program.
    System.out.println(e.getMessage());
    System.exit(1);
}

KernelLink ml = null;
try {
    ml = MathLinkFactory.createKernelLink("-linkmode launch -linkname 'c:\\program files\\wolfram research\\mathematica\\6.0\\mathkernel'");
} catch (MathLinkException e) {
    System.out.println("Link could not be created: " + e.getMessage());
    return; // Or whatever is appropriate.
}

try {
    connect(10000); // Wait at most 10 seconds
} catch (MathLinkException e) {
    // If the timeout expires, a MathLinkException will be thrown.
    System.out.println("Failure to connect link: " + e.getMessage());
    ml.close();
    return; // Or whatever is appropriate.
}

Using Listen and Connect Modes

Using a Remote Kernel

math -mathlink -linkmode listen -linkname 1234 -linkprotocol tcpip

KernelLink ml = MathLinkFactory.createKernelLink("-linkmode connect -linkprotocol tcpip -linkname 1234@remotemachinename");

KernelLink ml = MathLinkFactory.createKernelLink("-linkmode listen -linkprotocol tcpip -linkname 1234");
Runtime.exec("c:\\program files\\wolfram research\\mathematica\\6.0\\systemfiles\\frontend\\binaries\\windows\\winrsh -m -q -h -l YourUsername -'math -mathlink -linkmode connect -linkprotocol tcpip -linkname 1234@localmachinename'");

The MathLink Interface

Managing Links

void close();

void connect() throws MathLinkException;

// Wait at most timeoutMillis for the connect to occur, then throw a MathLinkException
void connect(long timeoutMillis) throws MathLinkException;

//A synonym for connect. This is the newer name.
void activate() throws MathLinkException; 

Packet Functions

//Does not throw exception because it will often be needed in a catch block.
void newPacket();

int nextPacket() throws MathLinkException;

void endPacket() throws MathLinkException;

Error Handling

int error();

boolean clearError();

String errorMessage();

void setError(int err);

Link State

boolean ready() throws MathLinkException;

Putting

void put(int i) throws MathLinkException;

void put(long i) throws MathLinkException;

void put(double d) throws MathLinkException;

void put(String s) throws MathLinkException;

void putByteString(byte[] b) throws MathLinkException;

void putSymbol(String s) throws MathLinkException;

void put(boolean b) throws MathLinkException;

void put(Object obj) throws MathLinkException;

void put(Object array, String[] heads) throws MathLinkException;

void putFunction(String f, int argCount) throws MathLinkException;

void transferExpression(MathLink source) throws MathLinkException;

void transferToEndOfLoopbackLink(LoopbackLink source) throws MathLinkException;

void putNext(int type) throws MathLinkException;

void putArgCount(int argCount) throws MathLinkException;

void putSize(int size) throws MathLinkException;

int bytesToPut() throws MathLinkException;

void putData(byte[] data) throws MathLinkException;

void putData(byte[] data, int len) throws MathLinkException;

void flush();

Getting

int getInteger() throws MathLinkException;

long getLongInteger() throws MathLinkException;

double getDouble() throws MathLinkException;

String getString() throws MathLinkException;

byte[] getByteString(int missing) throws MathLinkException;

String getSymbol() throws MathLinkException;

boolean getBoolean() throws MathLinkException;

int[] getIntArray1() throws MathLinkException;

int[][] getIntArray2() throws MathLinkException;

... and others for all the eight primitive types and String and the complex class

Object getArray(int type, int depth) throws MathLinkException;

// New in J/Link 2.0:
Object getArray(int type, int depth, String[] heads) throws MathLinkException;

MLFunction getFunction() throws MathLinkException;

// Returns the function's argument count. Throws MathLinkException if the function
// is not the specified one.
int checkFunction(String f) throws MathLinkException;

//Throws an exception if the incoming function does not have this head and arg count.
void checkFunctionWithArgCount(String f, int argCount) throws MathLinkException;

int getNext() throws MathLinkException;

int getType() throws MathLinkException;

int getArgCount() throws MathLinkException;

int bytesToGet() throws MathLinkException;

byte[] getData(int len) throws MathLinkException;

public Expr getExpr() throws MathLinkException;

// Gets an expression off the link, then resets the link to the state
// prior to reading the expr. You can "peek" ahead without consuming anything
// off the link.
public Expr peekExpr() throws MathLinkException;

Messages

int getMessage() throws MathLinkException;

void putMessage(int msg) throws MathLinkException;

boolean messageReady() throws MathLinkException;

Marks

long createMark() throws MathLinkException;

//Next two don't throw, since they are often used in cleanup operations in catch handlers.

void seekMark(long mark);

void destroyMark(long mark);

Complex Class

public boolean setComplexClass(Class cls);

public Class getComplexClass();

public Object getComplex() throws MathLinkException;

Yield and Message Handlers

public boolean setYieldFunction(Class cls, Object obj, String methName);

public boolean addMessageHandler(Class cls, Object obj, String methName);

public boolean removeMessageHandler(String methName);

Constants

static int ILLEGALPKT;
static int CALLPKT;
static int EVALUATEPKT;
static int RETURNPKT;
static int INPUTNAMEPKT;
static int ENTERTEXTPKT;
static int ENTEREXPRPKT;
static int OUTPUTNAMEPKT;
static int RETURNTEXTPKT;
static int RETURNEXPRPKT;
static int DISPLAYPKT;
static int DISPLAYENDPKT;
static int MESSAGEPKT;
static int TEXTPKT;
static int INPUTPKT;
static int INPUTSTRPKT;
static int MENUPKT;
static int SYNTAXPKT;
static int SUSPENDPKT;
static int RESUMEPKT;
static int BEGINDLGPKT;
static int ENDDLGPKT;
static int FIRSTUSERPKT;
static int LASTUSERPKT;

//These next two are unique to J/Link.
static int FEPKT;
static int EXPRESSIONPKT;

static int MLTERMINATEMESSAGE;
static int MLINTERRUPTMESSAGE;
static int MLABORTMESSAGE;

static int MLTKFUNC;
static int MLTKSTR;
static int MLTKSYM;
static int MLTKREAL;
static int MLTKINT;
static int MLTKERR;

//Constants for use in getArray()
static int TYPE_BOOLEAN;
static int TYPE_BYTE;
static int TYPE_CHAR;
static int TYPE_SHORT;
static int TYPE_INT;
static int TYPE_LONG;
static int TYPE_FLOAT;
static int TYPE_DOUBLE;
static int TYPE_STRING;
static int TYPE_BIGINTEGER;
static int TYPE_BIGDECIMAL;
static int TYPE_EXPR;
static int TYPE_COMPLEX;

The KernelLink Interface

Evaluate

void evaluate(String s) throws MathLinkException;

void evaluate(Expr e) throws MathLinkException;

Waiting for the Result

void waitForAnswer() throws MathLinkException;

void discardAnswer() throws MathLinkException;

The "evaluateTo" Methods

String evaluateToInputForm(String s, int pageWidth);
String evaluateToInputForm(Expr e, int pageWidth);

String evaluateToOutputForm(String s, int pageWidth);
String evaluateToOutputForm(Expr e, int pageWidth);

byte[] evaluateToImage(String s, int width, int height);
byte[] evaluateToImage(Expr e, int width, int height);
byte[] evaluateToImage(String s, int width, int height, int dpi, boolean useFrontEnd);
byte[] evaluateToImage(Expr e, int width, int height, int dpi, boolean useFrontEnd);

byte[] evaluateToTypeset(String s, int pageWidth, boolean useStdForm);
byte[] evaluateToTypeset(Expr e, int pageWidth, boolean useStdForm);

// Returns the exception that caused the most recent "evaluateTo" method to return null
Throwable getLastError();

Sending Java Object References

void enableObjectReferences() throws MathLinkException;

void put(Object obj) throws MathLinkException;

public void putReference(Object obj) throws MathLinkException;

Object getObject() throws MathLinkException;

// These two methods from the MathLink interface are enhanced to return MLTKOBJECT if a Java
// object reference is waiting to be read.
int getNext() throws MathLinkException;
int getType() throws MathLinkException;

Interrupting, Aborting, and Abandoning Evaluations

void abortEvaluation();
void interruptEvaluation()    
void abandonEvaluation();

void terminateKernel();

Support for PacketListeners

void addPacketListener(PacketListener listener);
void removePacketListener(PacketListener listener);

boolean notifyPacketListeners(int pkt);

The handlePacket() Method (Advanced Users Only)

void handlePacket(int pkt) throws MathLinkException;

Methods Valid Only for "StdLinks"

public void print(String s);
public void message(String symtag, String[] args);
public void message(String symtag, String arg);
public void beginManual();
    
public boolean wasInterrupted();
public void clearInterrupt();

Sending Computations and Reading Results

MathLink Packets

The MathLink "Packet Loop"

// C code
MLPutFunction(ml, "EvaluatePacket", 1);
MLPutFunction(ml, "ToExpression", 1);
MLPutString(ml, "Needs[\"MyPackage`\"]");
MLEndPacket(ml);
while (MLNextPacket(ml)  RETURNPKT)
    MLNewPacket(ml);
MLNewPacket();

ml.evaluate("Needs[\"MyPackage`\"]");
ml.discardAnswer();

Sending an Evaluation

String strResult = ml.evaluateToInputForm("NIntegrate[x^2 + y^2, {x,-1,1}, {y,-1,1}]");

ml.evaluate("NIntegrate[x^2 + y^2, {x,-1,1}, {y,-1,1}]");
ml.waitForAnswer();
double doubleResult1 = ml.getDouble();

// It is convenient to use indentation to indicate the structure
ml.putFunction("EvaluatePacket", 1);
  ml.putFunction("NIntegrate", 3);
    ml.putFunction("Plus", 2);
      ml.putFunction("Power", 2);
        ml.putSymbol("x");
        ml.put(2);
      ml.putFunction("Power", 2);
        ml.putSymbol("y");
        ml.put(2);
    ml.putFunction("List", 3);
      ml.putSymbol("x");
      ml.put(-1);
      ml.put(1);
    ml.putFunction("List", 3);
      ml.putSymbol("y");
      ml.put(-1);
      ml.put(1);
ml.endPacket();
ml.waitForAnswer();
double doubleResult2 = ml.getDouble();

Reading the Result

ml.evaluate("SomeFunction[]");
ml.waitForAnswer();
int result;
int type = ml.getNext();
if (type  MathLink.MLTKINT) {
    result = ml.getInteger();
} else {
    // What you do here is up to you.
    System.out.println("Unexpected result: " + ml.getExpr().toString());
    // Throw away the packet contents.
    ml.newPacket();
}

ml.evaluate("SomeFunction[]");
ml.waitForAnswer();
int result;
Expr e = ml.getExpr();
if (e.integerQ()) {
    result = e.asInt();
} else {
    // What you do here is up to you.
    System.out.println("Unexpected result: " + e.toString());
}

ml.evaluate("SomeFunction[]");
ml.waitForAnswer();
int result;
try {
    result = ml.getInteger();
} catch (MathLinkException e) {
    ml.clearError();
    System.out.println("Unexpected result: " + ml.getExpr().toString());
    ml.newPacket(); // Not strictly necessary because of the getExpr() above
}

ml.evaluate("SomeFunction[]");
ml.waitForAnswer();
int result;
try {
    result = ml.getInteger();
} catch (MathLinkException e) {
    ml.clearError();
    System.out.println("Unexpected result");
    // Oops. Forgot to call newPacket() to throw away the contents.
}

// Boom. The next line causes a MathLinkException if the previous getInteger()
// call failed, because nextPacket() will be called before the previous packet
// was emptied.
ml.evaluate("AnotherFunction[]");
ml.discardAnswer();

ml.evaluate("SomeFunction[]");
ml.waitForAnswer();
// Oops. Forgot to read or throw away the result.
// Probably meant to call discardAnswer() instead of
// waitForAnswer().

ml.evaluate("AnotherFunction[]");
ml.discardAnswer();   // MathLinkException here!

The "evaluateTo" Methods

String evaluateToInputForm(String s,int pageWidth);
String evaluateToInputForm(Expr e,int pageWidth);

String evaluateToOutputForm(String s,int pageWidth);
String evaluateToOutputForm(Expr e,int pageWidth);

byte[] evaluateToImage(String s, int width, int height);
byte[] evaluateToImage(Expr e, int width, int height);
byte[] evaluateToImage(String s, int width, int height, int dpi, boolean useFE);
byte[] evaluateToImage(Expr e, int width, int height, int dpi, boolean useFE);

byte[] evaluateToTypeset(String s, int width, boolean useStdForm);
byte[] evaluateToTypeset(Expr e, int width, boolean useStdForm);

// Give the (caught) exception that prevented a normal return from the last
// call to an "evaluateTo" method.
Throwable getLastError();

// This duplicates the following:
// String output = ml.evaluateToOutputForm("Integrate[5 x^n a^x, x]", 0);

// As an expression, we send ToString[Integrate[5 x^n a^x, x], PageWidth->Infinity]
ml.putFunction("EvaluatePacket", 1);
    ml.putFunction("ToString", 2);
    ml.putFunction("Integrate", 2);
          ml.putFunction("Times", 3);
              ml.put(5);
              ml.putFunction("Power", 2);
                  ml.putSymbol("x");
                  ml.putSymbol("n");
              ml.putFunction("Power", 2);
                  ml.putSymbol("a");
                  ml.putSymbol("x");
          ml.putSymbol("x");
       ml.putFunction("Rule", 2);
          ml.putSymbol("PageWidth");
          ml.putSymbol("x");
ml.endPacket();
ml.waitForAnswer();
String output = ml.getString();

LoopbackLink loop = MathLinkFactory.createLoopbackLink();

// Create the expression EvaluatePacket[Integrate[5 x^n a^x, x]] on the loopback link
loop.putFunction("Integrate", 2);
    loop.putFunction("Times", 3);
        loop.put(5);
        loop.putFunction("Power", 2);
            loop.putSymbol("x");
            loop.putSymbol("n");
        loop.putFunction("Power", 2);
            loop.putSymbol("a");
            loop.putSymbol("x");
    loop.putSymbol("x");
loop.endPacket();

// Now read the Expr off the loopback link
Expr e = loop.getExpr();
// We are done with the loopback link now.
loop.close();
String result = ml.evaluateToOutputForm(e, 0);
e.dispose();

Using the PacketListener Interface

public boolean packetArrived(PacketArrivedEvent evt) throws MathLinkException;

public boolean packetArrived(PacketArrivedEvent evt) throws MathLinkException {
    if (evt.getPktType()  MathLink.TEXTPKT) {
        KernelLink ml = (KernelLink) evt.getSource();
        System.out.println(ml.getString()); 
    }
    return true;
}

The PacketPrinter Class for Debugging

public PacketPrinter(PrintStream strm);

PacketListener stdoutPrinter = new PacketPrinter(System.out);
ml.addPacketListener(stdoutPrinter);
...
String result = ml.evaluateToOutputForm("Integrate[x^n a^x, x]", 72);

Using EnterTextPacket

String inputString = getStringFromUser();
ml.putFunction("EnterTextPacket", 1);
ml.put(inputString);
String result = null;
int pkt = ml.waitForAnswer();
if (pkt  MathLink.RETURNTEXTPKT) {
    // Mathematica computation returned a non-Null result, so a RETURNTEXTPKT
    // was generated. Read its contents (a string).
    result = ml.getString();
    // Now call waitForAnswer() again, which will return after opening the
    // InputNamePacket that will always follow. It is essentially
    // nothing more than a call to nextPacket() in this circumstance:
    ml.waitForAnswer();
}
// At this point, a call to waitForAnswer() has returned MathLink.INPUTNAMEPKT,
// so we just read out the contents, which is the next input prompt.
String nextPrompt = ml.getString();

Handling MathLinkExceptions

try {
    ...
} catch (MathLinkException e) {
    System.err.println(e.toString());
    if (ml.clearError()  true)    {
        System.err.println("MathLinkException was unrecoverable; closing link.");
        ml.close();
        return;  // Or whatever cleanup is appropriate
    }
    // How you respond after clearError is up to you.
}

// Some useful MathLinkException methods.
public int getErrCode();
public String getMessage();
public String toString();
public Throwable getCause();

Graphics and Typeset Output

Preamble

MathCanvas and MathGraphicsJPanel

public void setMathCommand(String cmd);
public void setImageType(int type);
public void setUsesFE(boolean useFE);
public void setUsesTraditionalForm(boolean useTradForm);

public void setImage(Image im);

public void recompute();

public void repaintNow();

A Sample Program That Displays Graphics and Typeset Results

(Windows)
java -classpath GraphicsApp.jar;..\..\..\JLink.jar GraphicsApp "c:\program files\wolfram research\mathematica\6.0\mathkernel"

(Unix)
java -classpath GraphicsApp.jar:../../../JLink.jar GraphicsApp 'math -mathlink'

(Mac OSX command line)
java -classpath GraphicsApp.jar:../../../JLink.jar GraphicsApp '"/Applications/Mathematica.app/Contents/MacOS/MathKernel" -mathlink'

import com.wolfram.jlink.*;
import java.awt.*;
import java.awt.event.*;

public class GraphicsApp extends Frame {
    
    static GraphicsApp app;
    static KernelLink ml;
    
    MathCanvas mathCanvas;
    TextArea inputTextArea;
    Button evalButton;
    Checkbox useFEButton;
    Checkbox graphicsButton;
    Checkbox typesetButton;

    public static void main(String[] argv) {

        try {
            String[] mlArgs = {"-linkmode", "launch", "-linkname", argv[0]};
            ml = MathLinkFactory.createKernelLink(mlArgs);
            ml.discardAnswer();
        } catch (MathLinkException e) {
            System.out.println("An error occurred connecting to the kernel.");
            if (ml  null)
                ml.close();
            return;
        }
        app = new GraphicsApp();
    }
    
    public GraphicsApp() {
        
        setLayout(null);
        setTitle("Graphics App");
        mathCanvas = new MathCanvas(ml);
        add(mathCanvas);
        mathCanvas.setBackground(Color.white);
        inputTextArea = new TextArea("", 2, 40, TextArea.SCROLLBARS_VERTICAL_ONLY);
        add(inputTextArea);
        evalButton = new Button("Evaluate");
        add(evalButton);
        evalButton.addActionListener(new BnAdptr());
        useFEButton = new Checkbox("Use front end", false);
        CheckboxGroup cg = new CheckboxGroup();
        graphicsButton = new Checkbox("Show graphics output", true, cg);
        typesetButton = new Checkbox("Show typeset result", false, cg);
        add(useFEButton);
        add(graphicsButton);
        add(typesetButton);
        
        setSize(300, 400);
        setLocation(100,100);
        mathCanvas.setBounds(10, 25, 280, 240);
        inputTextArea.setBounds(10, 270, 210, 60);
        evalButton.setBounds(230, 290, 60, 30);
        graphicsButton.setBounds(20, 340, 160, 20);
        typesetButton.setBounds(20, 365, 160, 20);
        useFEButton.setBounds(180, 340, 100, 20);
        
        addWindowListener(new WnAdptr());
        setBackground(Color.lightGray);
        setResizable(false);
        
        // Although this code would automatically be called in
        // evaluateToImage or evaluateToTypeset, it can cause the
        // front end window to come in front of this Java window.
        // Thus, it is best to get it out of the way at the start
        // and call toFront to put this window back in front.
        // KernelLink.PACKAGE_CONTEXT is just "JLink`", but it is
        // preferable to use this symbolic constant instead of
        // hard-coding the package context.
        ml.evaluateToInputForm("Needs[\"" + KernelLink.PACKAGE_CONTEXT + "\"]", 0);
        ml.evaluateToInputForm("ConnectToFrontEnd[]", 0);
        
        setVisible(true);
        toFront();
    }

    
    class BnAdptr implements ActionListener {
        public void actionPerformed(ActionEvent e) {
            mathCanvas.setImageType(
                graphicsButton.getState() ? MathCanvas.GRAPHICS : MathCanvas.TYPESET);
            mathCanvas.setUsesFE(useFEButton.getState());
            mathCanvas.setMathCommand(inputTextArea.getText());
        }
    }
    
    class WnAdptr extends WindowAdapter {
        public void windowClosing(WindowEvent event) {
            if (ml  null) {
                // Because we used the front end, it is important
                // to call CloseFrontEnd[] before closing the link.
                // Counterintuitively, this is not because we want
                // to force the front end to quit, but because we
                // _don't_ want to do this if the user has begun
                // working in the front end session we started.
                // CloseFrontEnd knows how to politely disengage
                // from the front end if necessary. The need for
                // this will go away in future releases of
                // Mathematica.
                ml.evaluateToInputForm("CloseFrontEnd[]", 0);
                ml.close();
            }
            dispose();
            System.exit(0);
        }
    }
}

evaluateToImage() and evaluateToTypeset()

// Specifies JPEG format for subsequent calls to evaluateToImage()
// and evaluateToTypeset().
ml.evaluateToOutputForm("$DefaultImageFormat = \"JPEG\"", 0);

(Windows)
java Typesetter "c:\program files\wolfram research\mathematica\6.0\mathkernel" "Sqrt[z]" test.gif

(Unix)
java Typesetter 'math -mathlink' "Sqrt[z]" test.gif

(Mac OSX command line)
java Typesetter '"/Applications/Mathematica.app/Contents/MacOS/MathKernel" -mathlink' "Sqrt[z]" test.gif

import com.wolfram.jlink.*;
import java.io.*;

public class Typesetter {
    
    public static void main(String[] argv) throws MathLinkException {
    
        KernelLink ml;        
        try {
            String[] mlArgs = {"-linkmode", "launch", "-linkname", argv[0]};
            ml = MathLinkFactory.createKernelLink(mlArgs);
            ml.discardAnswer();
        } catch (MathLinkException e) {
            System.err.println("FATAL ERROR: link creation failed.");
            return;
        }        
        byte[] gifData = ml.evaluateToTypeset(argv[1], 0, false);
        try {
            FileOutputStream s = new FileOutputStream(new File(argv[2]));
            s.write(gifData);
            s.close();
        } catch (IOException e) {}
        // ALWAYS execute CloseFrontEnd[] before killing the kernel if you used
        // evaluateToTypeset(), or evaluateToImage() with the useFE parameter
        // set to true:
        ml.evaluateToOutputForm("CloseFrontEnd[]", 0);
        ml.close();
    }
}

Aborting and Interrupting Computations

void abortEvaluation();
void interruptEvaluation()    
void abandonEvaluation();
void terminateKernel();

// On thread 1
ml.evaluate("Do[2+2, {20000000}]");
ml.waitForAnswer();
// If user aborted, the result will be the symbol $Aborted.
    
// On thread 2
if (userPressedEscKey() || timeoutElapsed())
    ml.abortEvaluation();

// On thread 1
try {
    ml.evaluate("While[True]");
    ml.discardAnswer();
} catch (MathLinkException e) {
    // We will get here when abandonEvaluation() is called on the other thread.
    System.err.println("MathLinkException occurred: " + e.toString());
    if (!ml.clearError()) {
        // clearError() will always fail when abandonEvaluation() was called.
        ml.terminateKernel();
        ml.close();
    }
}
    
// On thread 2
if (timeoutElapsedAndReallyNeedToShutdownKernel())
    ml.abandonEvaluation();

Using Marks

// In the MathLink interface:
long createMark() throws MathLinkException;
void seekMark(long mark);
void destroyMark(long mark);

String head = null;
long mark = ml.createMark();
try {
    head = ml.getFunction().name;
    ml.seekMark(mark);
} finally {
    ml.destroyMark(mark);
}
if (head.equals("foo"))
    handleFoo(ml);
else if (head.equals("bar"))
    handleBar(ml);

double[] data = null;
long mark = ml.createMark();
ty {
    data = ml.getDoubleArray1();
} catch (MathLinkException e) {
    ml.clearError();
    ml.seekMark(mark);
    // Here, try a different way of reading the data:
    switch (ml.getNext()) {
        ... 
    }
} finally {
    ml.destroyMark(mark);
}

Using Loopback Links

// In class MathLinkFactory:
public static LoopbackLink createLoopbackLink() throws MathLinkException;

// In the MathLink interface
void transferExpression(MathLink source) throws MathLinkException;
void transferToEndOfLoopbackLink(LoopbackLink source) throws MathLinkException;

// Here we demonstrate sending an expression (a list of reals)
// whose length is unknown at the start.
try {
    ...
    LoopbackLink loop = MathLinkFactory.createLoopbackLink();
    int count = 0;
    while (someTest) {
        loop.put(Math.random());
        count++;
    }
    ml.putFunction("List", count);
    ml.transferToEndOfLoopbackLink(loop);
    loop.close();
    ...
} catch (MathLinkException e) {}

Using Expr Objects

Motivation for the Expr Class

ml.evaluate("some code");
ml.waitForAnswer();
Expr e = ml.getExpr();
Expr part23 = e.part(new int[] {2, 3});
boolean isVector = part23.vectorQ();

Methods in the MathLink Interface for Reading and Writing Exprs

// In the MathLink interface:
Expr getExpr() throws MathLinkException;
Expr peekExpr() throws MathLinkException;
void put(Object obj) throws MathLinkException;

Exprs as Replacements for Loopback Links

// Old way, using a loopback link
    LoopbackLink loop = MathLinkFactory.createLoopbackLink();
    // Read expr off of link and store it on loopback
    loop.transferExpression(ml);
    ...
    // Later, write the expr back on the link
    ml.transferExpression(loop);
    loop.close();

// New way, using an Expr
    Expr e = ml.getExpr();
    ...
    // Later, write the expression back on the link
    ml.put(e);
    e.dispose();

Exprs as a Means to Get String Representations of Expressions

public boolean packetArrived(PacketArrivedEvent evt) throws MathLinkException {
    KernelLink ml = (KernelLink) evt.getSource();
    Expr e = ml.getExpr();
    strm.println("Packet type was " + pktToName(evt.getPktType()) + 
                    ". Contents follows."); 
    strm.println(e.toString());
    e.dispose();
    return true;
}

Exprs as Arguments to KernelLink Methods

// Send input as a string:
    String result = MathLink.evaluateToOutputForm("2+2", 0);
    
// Send input as an Expr:
    LoopbackLink loop = MathLinkFactory.createLoopbackLink();
    // Create the expression 2+2 on the loopback link
    loop.putFunction("Plus", 2);
        loop.put(2);
        loop.put(2);
    loop.endPacket();
    // Now read the Expr off the loopback link
    Expr e = loop.getExpr();
    // We are done with the loopback link now.
    loop.close();
    String result = ml.evaluateToOutputForm(e, 0);
    e.dispose();

Examining and Manipulating Exprs

public Expr head();
public Expr[] args();
public int length();
public int[] dimensions();

// A sampling of the "Q" methods
public boolean atomQ();
public boolean stringQ();
public boolean integerQ();
public boolean numberQ();
public boolean trueQ();
public boolean listQ();
public boolean vectorQ();
public boolean matrixQ();

public Expr part(int index);
public Expr part(int[] indices);
public Expr take(int n);
public Expr delete(int n);
public Expr insert(Expr e, int n);

ml.evaluate("Expand[(x + y)^4]");
ml.waitForAnswer();
Expr e1 = ml.getExpr();

System.out.println("e1 is:  " + e1.toString());
System.out.println("the length is:  " + e1.length());
System.out.println("the head is:  " + e1.head().toString());
System.out.println("part [[2]] is:  " + e1.part(2));
System.out.println("part [[-1]] is:  " + e1.part(-1));
System.out.println("part [[2, 2]] is:  " + e1.part(new int[]{2, 2}));
System.out.println("drop the last element:  " + e1.delete(-1).toString());
System.out.println("e1 is unmodified:  " + e1.toString());
Expr e2 = e1.insert(new Expr(new double[] {1.0, 2.0, 3.0}), 1);
System.out.println("e2 is:  " + e2.toString());

e1 is:  Plus[Power[x,3],Times[3,Power[x,2],y],Times[3,x,Power[y,2]],Power[y,3]]
the length is:  4
the head is:  Plus
part [[2]] is:  Times[3,Power[x,2],y]
part [[-1]] is:  Power[y,3]
part [[2, 2]] is:  Power[x,2]
drop the last element:  Plus[Power[x,3],Times[3,Power[x,2],y],Times[3,x,Power[y,2]]]
e1 is unmodified:  Plus[Power[x,3],Times[3,Power[x,2],y],Times[3,x,Power[y,2]],Power[y,3]]
e2 is:  Plus[{1.0,2.0,3.0},Power[x,3],Times[3,Power[x,2],y],Times[3,x,Power[y,2]],Power[y,3]]

Disposing of Exprs

System.out.println("the result was " + ml.getExpr().toString());

Expr e = ml.getExpr();
System.out.println("the result was " + e.toString());
e.dispose();

Expr e = ml.getExpr();
// The moment that head() or part() are called on e below, you know that neither
// e, e2, nor e3 need to be disposed.
Expr e2 = e.head();
Expr e3 = e.part(1);

Threads, Blocking, and Yielding

synchronized (ml) {
    ml.evaluate("2+2");
    ml.waitForAnswer();
    int result = ml.getInteger();
}

// From the MathLink interface
public boolean setYieldFunction(Class cls, Object obj, String methName);

public boolean myYielder();

Sending Object References to Mathematica

public void enableObjectReferences() throws MathLinkException;

// For sending object references:
public void put(Object obj) throws MathLinkException;
public void putReference(Object obj) throws MathLinkException;

public Object getObject() throws MathLinkException;

// ml.enableObjectReferences() must have been called prior, for example
// in the servlet's init method.
public void doGet(HttpServletRequest req, HttpServletResponse res)
                    throws ServletException, IOException {
    try {
        ml.putFunction("EvaluatePacket", 1);
        ml.putFunction("DoGet", 2);
        // We could also use plain 'put' here, as these objects would be put
        // by reference anyway.
        ml.putReference(req);
        ml.putReference(res);
        ml.endPacket();
        ml.discardAnswer();
    } catch (MathLinkException e) {}
}

doGet[req_, resp_] :=
     JavaBlock[
        Module[{outStream},
            outStream = resp@getOutputStream[];
            outStream@print["<HTML> <BODY>"];
            outStream@print["Hello World"];
            outStream@print["</BODY> </HTML>"];
        ]
    ]
]

Some Special User Interface Classes

Introduction

ConsoleWindow

// Don't forget to import it (a different package than the rest of J/Link):
// import com.wolfram.jlink.ui.ConsoleWindow;

ConsoleWindow cw = ConsoleWindow.getInstance();
cw.setLocation(100, 100);
cw.setSize(450, 400);
cw.show();
// specify that we want to capture System.out and System.err.
cw.setCapture(ConsoleWindow.STDOUT | ConsoleWindow.STDERR);
System.out.println("hello world from stdout");
System.err.println("hello world from stderr");

MathSessionPane

(Windows)
java -classpath SimpleFrontEnd.jar;..\..\..\JLink.jar SimpleFrontEnd

(Linux, Unix, Mac OS X):
java -classpath SimpleFrontEnd.jar:../../../JLink.jar SimpleFrontEnd

BracketMatcher and SyntaxTokenizer

InterruptDialog

// Don't forget to import it (a different package than the rest of J/Link):
// import com.wolfram.jlink.ui.InterruptDialog;

ml.addPacketListener(new InterruptDialog(myParentFrame));

Writing Applets