com.wolfram.jlink

Class StdLink

java.lang.Object

com.wolfram.jlink.StdLink

public class StdLink
extends java.lang.Object

StdLink contains two methods that you use to interact with the link back to the kernel in cases where Java is "installed" into Mathematica (that is, InstallJava[] has been called in the Mathematica session). The getLink() method returns this link, and requestTransaction() must be called from the user-interface thread before calling into Mathematica.

You never create or use an instance of StdLink; it simply is a container for some methods and state related to the link back to the kernel. The name is inspired by the 'stdlink' global variable that holds the link in C-language "installable" MathLink programs generated by the mprep tool.

Constructor Summary

Constructors

Constructor and Description
StdLink()

Method Summary

Methods

Modifier and Type	Method and Description
static KernelLink	getLink() When called during a session when Java is "installed" into Mathematica (i.e., InstallJava[] has been called in Mathematica), getLink() returns the KernelLink that points back to Mathematica.
static KernelLink	getMainLink()
static KernelLink	getUILink()
static void	requestTransaction() Must be called from code that calls into Mathematica from the user-interface thread.
static void	setLink(KernelLink ml) Sets the link that will be returned by getLink() when the program is not in the middle of a call from Mathematica.
static void	setUILink(KernelLink uiLink)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

StdLink

public StdLink()

Method Detail

getLink

public static KernelLink getLink()

When called during a session when Java is "installed" into Mathematica (i.e., InstallJava[] has been called in Mathematica), getLink() returns the KernelLink that points back to Mathematica. It returns null if Java is not being used from Mathematica. Java methods need to obtain the link back to Mathematica in a number of circumstances, such as if they want to return a result to Mathematica manually, or trigger computations in Mathematica before they return, or if they are called from the user-interface thread in response to a user action like clicking a button.

Here is an example of how it might be called in a method that wants to return a result to Mathematica manually, instead of having its normal return value sent back.

        KernelLink link = StdLink.getLink();
        if (link != null) {
                link.beginManual();
                ... code here to put a result to Mathematica
        }

setLink

public static void setLink(KernelLink ml)

Sets the link that will be returned by getLink() when the program is not in the middle of a call from Mathematica. The reason this is useful is that you might want to migrate a program that was originally written to be scripted from Mathematica into a standalone mode (where the program is the kernel's $ParentLink and the notebook front end is no longer involved). Alternatively, you might want to maintain dual-mode functionality, where a class can be instantiated and scripted from a Mathematica session but also has a main() method that lets it run standalone. In either of these circumstances, you may have code that calls StdLink.getLink() to give the link back to Mathematica. By exposing setLink(), J/Link lets you assign the "StdLink" yourself, so that you don't have to modify all the code that calls StdLink.getLink(). You are spared from having to keep track of whether your program is being scripted (and thus has a valid StdLink) or not.

Parameters:

ml -

Since:

J/Link version 1.1.2

requestTransaction

public static void requestTransaction()

Must be called from code that calls into Mathematica from the user-interface thread. For each computation you want to send, you must call requestTransaction prior. The requestTransaction method will block until Mathematica is in a state ready to accept incoming evaluations from Java. Examples of code that needs to use requestTransaction are the various "MathListener" classes, which trigger calls into Mathematica as the result of a user action in Java (such as clicking a button or dragging a slider). Examples of code that does not need to call requestTransaction are the typical callbacks from Java methods that are themselves being called from Mathematica. In other words, you only need to use requestTransaction if the call into Mathematica originates from Java (like a user-interface action), not if it is part of a chain of back-and-forth calls that includes Mathematica calling into Java.

If you are writing a "listener"-type class (i.e., one that implements java.util.EventListener) that calls into Mathematica as a result of some user action on the user-interface thread, you should consider making your class a subclass of MathListener. The MathListener class handles all the details of the interaction with Mathematica for you, including calling requestTransaction().

Here is a typical example of code that calls requestTransaction(). Note that the code that sends the evaluation and reads the answer must still be in a synchronized block. This synchronization solves a different problem than requestTransaction(). Make sure you enter the synchronized block after requestTransaction(), or the user-interface thread will hang forever.

     KernelLink ml = StdLink.getLink();
     StdLink.requestTransaction();
     synchronized (ml) {
         try {
             ml.evaluate("buttonClickFunction[]");
             ml.discardAnswer();
             // evaluate() sends an EvaluatePacket. You could also send the EvaluatePacket manually:
             //ml.putFunction("EvaluatePacket", 1);
             //ml.putFunction("ToExpression", 1);
             //ml.put("buttonClickFunction[]");
             //ml.discardAnswer();
         } catch (MathLinkException e) {}
     }

setUILink

public static void setUILink(KernelLink uiLink)

getUILink

public static KernelLink getUILink()

getMainLink

public static KernelLink getMainLink()