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.
This version of J/Link is the one that ships with Mathematica 5.1.
J/Link runs on Windows, Macintosh OSX, 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.
| 3.0.0 | 9/04 | Complete revamp to the ShareKernel system for Mathematica 5.1. The kernel is now always shared with Java, so ShareKernel[] does nothing. Modeless Java GUIs can now preempt Mathematica computations, so GUIs remain responsive even while the kernel is computing something else. KeepJavaObject now supports a Manual argument that causes the object to never be automatically released, no matter how many levels of enclosing JavaBlocks there are. Several minor bug fixes. |
| 2.1.1 | 9/03 | Several minor bug fixes. Built with new revision of the MathLink library on Unix/OSX. |
| 2.1.0 | 4/03 | Several fixes; changes for compatibility with .NET/Link. Support is dropped for the Microsoft Java runtime. Use .NET/Link if you need to call COM objects from Mathematica. Support is dropped for Macintosh System 8 and 9. |
| 2.0.2 | 6/02 | Minor update for Linux-IA64 support. |
| 2.0.1 | 6/02 | Minor bug-fix update for version 2.0.0. |
| 2.0.0 | 5/02 | Major upgrade to 1.1 with many new features. Number changed to 2.0 (instead of 1.2) to reflect large changes from 1.1. This version shipped with Mathematica 4.2.0. |
| 1.2.0b3 | 11/01 | Major upgrade with many new features. This is a feature- complete mature beta version for early release with Mac OS X. |
| 1.1.3 | 7/23/01 | Minor upgrade to support webMathematica. Windows and Mac users need not upgrade unless they intend to run webMathematica. UNIX users will want this version, as it is linked with a newer MathLink library that provides much better performance. Also, the native library is provided for more varieties of UNIX. |
| 1.1.2 | 12/12/00 | PDF (Acrobat) version of the User Guide is included. Resources can now be found in jar files on $ExtraClassPath. Improvement in InstallJava for Windows users. JLink.jar now marks relevant classes as JavaBeans. Small changes in User Guide to fix some sample code that used Expr objects. |
| 1.1.1 | 11/11/00 | Minor bug fixed. Relevant for Windows only. |
| 1.1 | 11/9/00 | Major upgrade. Not-quite-final version ships on the Mathematica 4.1.0 CD. |
| 1.0.1 | 2/00 | Minor revision to 1.0. |
| 1.0 | 12/99 | First release. |
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 OSX. 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.
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.
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., theSystem.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.
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).
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.
SetOptions[InstallJava, CommandLine->"c:\\jdk1.3\\bin\\java.exe"]; InstallJava[]
If you do this, you won't need the 1.1.1 revision anyway.
The J/Link native library (libJLinkNativeLibrary.so) for glibc 2.0 Linux users is fixed.
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.