2.7 The KernelLink Interface
KernelLink is the interface that you will probably use for the links in your programs. These are all public methods, as is always the case with a Java interface. This section provides only a brief summary of the KernelLink methods; it is intended mainly for those who want to skim a traditional printed listing. The JavaDoc help files are the main method-by-method documentation for all the J/Link classes and interfaces. They can be found in the JLink/Documentation/JavaDoc directory.
The evaluate() method encapsulates the steps needed to put an expression to Mathematica as a string or Expr and get the answer back as an expression. Internally, it uses an EvaluatePacket for sending the expression. The answer comes back in a ReturnPacket, although the waitForAnswer() method opens up the ReturnPacket—all you have to do is read out its contents. You should always use waitForAnswer() or discardAnswer() instead of spinning your own packet loop waiting for a ReturnPacket. See Section 2.8.2.
void evaluate(String s) throws MathLinkException;
void evaluate(Expr e) throws MathLinkException;
2.7.2 Waiting for the Result
Call waitForAnswer() right after evaluate() (or if you manually send calculations wrapped in EvaluatePacket). It will read packets off the link until it encounters a ReturnPacket, which will hold the result. See Section 2.8.2.
void waitForAnswer() throws MathLinkException;
The discardAnswer() method just throws away all the results from the calculation, so the link will be ready for the next calculation. As you may have guessed, it is nothing more than waitForAnswer() followed by newPacket().
void discardAnswer() throws MathLinkException;
2.7.3 The "evaluateTo" Methods
The next set of methods are extensions of evaluate() that perform the put and the reading of the result. You do not call waitForAnswer() and then read the result yourself. They also do not throw MathLinkException—if there is an error, they clean up for you and return null. The "evaluateTo" in their names indicates that the methods perform the entire process themselves. evaluateToInputForm() returns a string formatted in InputForm at the specified page width. Specify 0 for the page width to get Infinity. evaluateToOutputForm() is exactly like evaluateToInputForm() except that it returns a string formatted in OutputForm. OutputForm results are more attractive for display to the user, but InputForm is required if you want to pass the string back to Mathematica to be used in further computations. The evaluateToImage() method will return a byte of GIF data if you give it an expression that returns a graphic, for example, a Plot command. Pass 0 for the dpi, int, and width arguments if you want their Automatic settings in Mathematica. evaluateToTypeset() returns a byte of GIF data of the result of the computation, typeset in either StandardForm or TraditionalForm. These methods are discussed in detail in Section 2.10.4.
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
2.7.4 Sending Java Object References
If you want to send Java objects "by reference" to Mathematica so that Mathematica code can call back into your Java runtime via the "installable Java" facility described in Part 1 of this manual, you must first call the enableObjectReferences() method. This is described in Section 2.16.
void enableObjectReferences() throws MathLinkException;
Like the MathLink interface, KernelLink has a put() method that sends objects. The MathLink version of this method only sends objects "by value." The KernelLink version behaves just like the MathLink version for those objects that can be sent by value. In addition, though, it sends all other objects by reference. You must have called enableObjectReferences() before calling put() on an object that will be sent by reference. See Section 2.16.
void put(Object obj) throws MathLinkException;
The next methods are for putting and getting objects by reference (you must have called enableObjectReferences() to use these methods).
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;
2.7.5 Interupting, Aborting, and Abandoning Evaluations
These methods are for aborting and interrupting evaluations. They are discussed in Section 2.11.
2.7.6 Support for PacketListeners
These methods support the registering and notification of PacketListeners. They are discussed in Section 2.8.6.
void addPacketListener(PacketListener listener);
void removePacketListener(PacketListener listener);
boolean notifyPacketListeners(int pkt);
2.7.7 The handlePacket() Method (Advanced Users Only)
The handlePacket() method is for very advanced users who are writing their own packet loop instead of calling waitForAnswer(), discardAnswer(), or any of the "evaluateTo" methods. See the JavaDocs for more information.
void handlePacket(int pkt) throws MathLinkException;
// Deprecated in J/Link 2.0; use handlePacket()
void handleCallPacket() throws MathLinkException;
2.7.8 Methods Valid Only for "StdLinks"
Finally, there are some methods that are meaningful only in methods that are themselves called from Mathematica via the "installable Java" functionality described in Part 1 of this User Guide. These methods are documented in Section 1.2.18. You will not use them if you are writing a program that uses Mathematica as a computational engine.
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();