J/Link 3.0.2 Release Notes

J/Link integrates Mathematica and Java by letting you call Java from Mathematica in a completely transparent way, and call Mathematica from Java with a very high-level API. In one sense, J/Link is a "MathLink Developer Kit for Java," but it is also much more than that. J/Link will appeal to many people, not just those who are interested in writing MathLink programs.

Users with Mathematica 4.2 and later will find that J/Link and a Java runtime environment are pre-installed and ready to use. Those with earlier versions of Mathematica, or those who want to update J/Link with a newer version downloaded from the web, will find installation instructions for J/Link in the InstallationInstructions.html file in the JLink directory included with the download.

This version of J/Link is identical to the one that ships with Mathematica 5.1.1, except that it incorporates one fix for a problem on Mac OS X 10.3.8.

J/Link runs on Windows, Macintosh OS X, Linux, and Unix. Information about requirements and how to obtain Java for your platform can be found in the User Guide, which will appear in the Mathematica Help Browser after J/Link is installed.

Revision History

Changes in Version 2.1.0

The Microsoft Java runtime is no longer supported. The new product .NET/Link is a far superior solution for interacting with COM objects.

Macintosh operating systems prior to OS X are no longer supported. Use an older version of J/Link if you need to run on System 8 or 9.

Several internal changes were made for compatibility with .NET/Link. .NET/Link users will need this version of J/Link or later.

Added the GetJavaException[] function, which returns the Java exception object thrown in the last call from Mathematica to Java, if there was one. Also added the variable $JavaExceptionHandler, which you can set to create your own exception-handling mechanism in Mathematica (for example, to prevent exceptions from causing messages to be displayed, or to hook into Mathematica's own Throw/Catch system). See the usage messages for more info.

Added the KeepJavaObject function, which lets you specify that a Java object should not be released when the enclosing JavaBlock ends. The KeepObjects option to JavaBlock is deprecated, having been superseded by this new function.

The Prompt option to ShareKernel is deprecated. It has been renamed to SharingPrompt.

Input[] and InputString[] no longer hang when called from Java while the front end is being shared. They now work as expected, causing an Input dialog to appear in the front end.

Added support for a property named com.wolfram.jlink.libdir, which specifies a path to the directory in which the J/Link native library is located. Define this property if your application requires the native library to be in a non-standard place.

Experimental support was added for a com.wolfram.jlink.nogui property on Mac OS X. Set this property to true in the JLink.app/Contents/Resources/MRJApp.properties file to prevent the J/Link application from showing up in the dock when it is launched via InstallJava[]. This is for specialty uses only. Windows and other GUI elements will not work properly in the Java session if you use this property.

Changes in Version 2.0.1

Fixes a bug that can cause the Java runtime to shut down in some circumstances on Java 1.1.x version runtimes (e.g., Mac OS 8/9, or Windows users using the Microsoft Java runtime).

Improves behavior of the Mathematica front end on Windows when it is launched to provide graphics rendering services for Java programs.

Fixes minor classpath problems on Mac OS 8/9.

Improves color scheme used by the ConsoleWindow class.

Changes in Version 2.0.0

Special Notes:

The location of JLink.jar within the JLink directory structure was changed in this release. Users of previous versions with CLASSPATH specifications that point at JLink.jar will need to revise them. JLink.jar is now in the JLink directory itself, not JLink/SystemAdditions.

A number of functions have been renamed. The old names are deprecated, meaning that they still work but might be removed in the future. All new code should use the new names. Here are the old and new names:

old name	new name
LoadClass	LoadJavaClass
ReleaseObject	ReleaseJavaObject
Val	JavaObjectToExpression
ByRef	ReturnAsJavaObject
GetClassPath	JavaClassPath

Version 2.0 is a significant upgrade with many new features and improvements. Here are the most important ones:

Mac OS X is supported.

Dramatic speed improvements have been made for calling Java methods. This makes the MethodFunction and FieldFunction optimizations more or less obsolete.

One of the most difficult parts of J/Link installation was putting the native library in the correct location. This is no longer necessary. The native library should remain where it is, buried deep in the JLink directory structure.

The way in which Java is launched by InstallJava is new. One consequence of this is that the ClassPath option works differently. The default setting, Automatic, means that the value of the CLASSPATH environment variable will be used. However, if you set a value for ClassPath, that value is used instead of the CLASSPATH environment variable.

There is a new component called com.wolfram.jlink.ui.MathSessionPane that implements a complete In/Out session window, similar to the kernel's raw "terminal" interface but with many more features, including: graphics support, syntax coloring of input, bracket matching, copy input from above, customizable colors and fonts, full text editing features within the current input "cell" including cut/copy/paste/undo/redo, and more.

A new component called MathGraphicsJPanel is the Swing counterpart to the existing AWT-based MathCanvas. Use this component to easily display Mathematica graphics and typeset expressions in your programs.

There is a new Mathematica function, ShowJavaConsole[], that displays a window showing Java console output (i.e., the System.out and System.err streams). On Windows, you no longer see a DOS Java console window appear when Java launches.

The JavaBlock function is improved to give it more control over what objects are released when it ends. These improvements make some common programming idioms easier, without having to resort to manual use of ReleaseObject. If you return a Java object as the sole result of a JavaBlock, that object is not released. There is also a new KeepObjects option to JavaBlock that allows you to specify a list of one or more objects that will not be released at the end.

The new ImplementJavaInterface function lets you implement any Java interface entirely with Mathematica code. Among other uses, this means that you can create any "listener"-type object in Mathematica without requiring a Java MathXXXHandler class to already exist for that interface.

There is a SetInternetProxy function that allows users to specify proxy port and host information, if such settings are necessary to reach the internet.

There is a new MakeJavaExpr[] function that lets you construct, from Mathematica, a Java Expr object from an arbitrary Mathematica expression.

The AddToClassPath function was added to supersede the functionality provided by $ExtraClassPath.

There is a new JLink`Information` context that defines symbols giving version information. The symbols are $Version, $VersionNumber, $ReleaseNumber.

Working with periodical tasks is now more flexible with the new function SetPeriodicalInterval and the new variable $ThisPeriodical.

For Java programmers, the MLGetType, MLGetNext methods when applied to a KernelLink object can now return KernelLink.MLTKOBJECT in addition to MLTKSTR, MLTKINT, etc. MLTKOBJECT means that the expression on the link is a Java object reference and can be read with getObject().

The MathLink connect() method now includes an optional timeout parameter giving the number of milliseconds to wait for the connection before throwing an exception.

The MathLink interface now has a second signature for the getArray method: getArray(int type, int depth, String[] heads). This method reads an array and tells you what the heads were at each level.

A getLastError() method was added to the KernelLink interface. If one of the evaluateTo methods returns null, you can call getLastError() to get the Throwable object that caused the problem.

The methods interruptEvaluation(), abortEvaluation(), abandonEvaluation(), and terminateKernel() were added to the KernelLink interface. These methods free the programmer from having to deal directly with low-level MathLink messages.

The Expr class has been extended and made faster and more robust.

Changes in Version 1.1.3

The J/Link native library in Version 1.1.2 for Solaris (and any libraries built by Unix users against the Mathematica 4.1 version of MathLink) had a serious flaw that greatly limited performance. Version 1.1.3 is now linked against a newer version of the MathLink library that fixes the speed problem.

The native library is now provided for PPC Linux, Linux-Alpha, HP/UX 10.20, and SGI IRIX (in addition to Macintosh, Windows, Linux-Intel, and Solaris).

Changes in Version 1.1.2

Version 1.1.2 has some Windows-only improvements in the behavior of InstallJava. InstallJava could take a long time on Windows if you have a directory on your path with a large number of files in it (say, > 2000 or so). This revision eliminates the problem.

Resources (such as gif files) located within jar files accessible to J/Link via the $ExtraClassPath facility are now read properly. Prior versions could not read such resources.

JLink.jar now marks the classes MathCanvas, MathFrame and MathJFrame as JavaBeans. This helps GUI builders recognize and import these classes into their frameworks. For example, in Visual Cafe® you can now drag JLink.jar into the Component Library and it will automatically detect these three classes and make them available for drag-and-drop in the GUI builder.

A small change was made in two places in the User Guide where Expr objects were created on LoopbackLinks and then sent to Mathematica via evaluateToOutputForm() (sections 2.8.3 and 2.14.5). The old sample code included the EvaluatePacket wrapper in the Expr itself, but that is incorrect.

Changes in Version 1.1.1

SetOptions[InstallJava, CommandLine->"c:\\jdk1.3\\bin\\java.exe"]; InstallJava[]

If you do this, you won't need the 1.1.1 revision anyway.

Changes from the J/Link 1.1 version on the Mathematica 4.1.0 CD to the Web release of 1.1.0

The J/Link native library (libJLinkNativeLibrary.so) for glibc 2.0 Linux users is fixed.

Changes in Version 1.1

The User Guide has been revised and some missing sections have been filled in. It is now provided as a Mathematica notebook to be viewed in the Mathematica Help Browser.

Large performance gains are realized on most platforms. The overhead of a single call from Mathematica into Java has dropped, so the rate at which calls can be made is much higher. Array transfers between Mathematica and Java are much faster for large multidimensional arrays. The $RelaxedTypeChecking flag is provided to let you make sending arrays to Java faster still by eliminating the Mathematica-side type checking on arrays.

A consequence of the above optimizations is that Unix/Linux users with Java runtimes that do not support native threads must set the flag $NativeThreads = False before calling InstallJava. This issue is discussed in sections 1.1.2 and 1.2.2 of the User Guide.

The MathCanvas class has been added to make it easy to display Mathematica graphics and typeset expressions in Java programs, or in Mathematica programs that produce Java windows.

The J/Link native library is provided for a larger number of varieties of Unix, including Solaris, so if you had to compile it in the previous release, you will probably not have to for this one.

Java methods that take real number types (double, float) can now usually be called from Mathematica with integer arguments, instead of requiring you to use N to convert such arguments to real numbers.

Ragged (i.e., non-rectangular) arrays can now be sent and received by Java. This is enabled by calling AllowRaggedArrays[True].

J/Link now uses its own class loader that is able to find classes that are not on the class path. You can specify directories and jar files to be searched by modifying the $ExtraClassPath variable. Applications that use J/Link can now put classes in their own private Java subdirectory and they will automatically be found by J/Link. This means that deploying an application that uses J/Link is as simple as dragging its directory into Mathematica's AddOns/Applications directory.

The KernelLinkCOM class has been added, which allows you to use the J/Link KernelLink API from Visual Basic, VBScript, and other COM-aware scripting languages.

Numerous other smaller enhancements and fixes have been included.

The problems Windows users have had due to Sun's JDK installer putting multiple copies of the JRE on their systems have been resolved. J/Link should now be able to find and use the same Java runtime that is invoked when java is executed from a DOS command line.

The bug causing J/Link to fail with a NoClassDefFoundError for most users trying to use the Microsoft Java runtime is fixed. This error was caused by an unnecessary dependence of J/Link on the RMI classes, which are not part of the default installation of Microsoft's Java.

An important change for programmers who have written MathListener-style classes

When calling into Mathematica from the Java user interface thread (like the J/Link MathListener classes do), you must call the new method StdLink.requestTransaction() first. If you have written your own MathListener-type class, the UI thread will hang if you fail to call this method before trying to call Mathematica. See "Writing Your Own Event Handler Code" in the User Guide for more details.