This is documentation for Mathematica 5, which was
based on an earlier version of the Wolfram Language.
View current documentation (Version 11.1)

Documentation / Mathematica / Add-ons & Links / J/Link / Part 2. Writing Java Programs That Use Mathematica /

2.1 Introduction

The first part of this User Guide describes using J/Link to allow you to call from Mathematica into Java, thereby extending the Mathematica environment to include the functionality in all existing and future Java classes. This part shows you how to use J/Link in the opposite direction, as a means to write Java programs that use the Mathematica kernel as a computational engine.

J/Link uses MathLink, Wolfram Research's protocol for sending data and commands between programs. Many of the concepts and techniques in J/Link programming are the same as those for programming with the MathLink C-language API. The J/Link documentation is not intended to be an encyclopedic compendium of everything you need to know to write Java programs that use MathLink. Programmers may have to rely a little on the general documentation of MathLink programming in The Mathematica Book. I also recommend this author's MathLink Tutorial, available on MathSource (http://www.mathsource.com/Content/Enhancements/MathLink/0206-693). The Tutorial is divided into two major sections along the same lines as this User Guide. You will want to read the second part. Many of the functions J/Link provides have C-language counterparts that are identical or nearly so.

If you have not read Part 1, "Calling Java from Mathematica," you should at least skim it at some point. Your Java "front end" can use the same techniques for calling Java methods from Mathematica code and passing Java objects as arguments that programmers use when running the kernel from the notebook front end. This allows you to have a very high-level interface between Java and Mathematica. When you are writing MathLink programs in C, you have to think about passing and returning simple things like strings and integers. With J/Link you can pass Java objects back and forth between Java and Mathematica. J/Link truly obliterates the boundary between Java and Mathematica.

Although Java is quite useful as a web-related development language, such as for writing applets or servlets, it is by no means restricted to this domain, and this User Guide does not address the specifics of these types of programs. We treat generic issues in J/Link programming, leaving the application of these concepts in specific types of programs up to the reader. In other words, if you are looking for a worked-out example program showing how a suite of servlets running on a web or application server can allow remote Java clients to share a cluster of Mathematica kernels, you won't find it here. But J/Link is just the sort of tool you will need if you embark on such a project.

This half of the manual is organized as follows. Section 2.2 is a very brief introduction to MathLink. Section 2.3 introduces the most important J/Link interfaces and classes. Section 2.4 presents a simple example program. Section 2.5 shows how to launch Mathematica and create links. Sections 2.6 and 2.7 give a listing of methods in the large and all-important MathLink and KernelLink interfaces. The methods are grouped by function, and there is some commentary mixed in. This treatment does not replace the actual JavaDoc help files for J/Link, found in the JLink/Documentation/JavaDoc directory. The JavaDoc files are the main method-by-method reference for J/Link, and they include all the classes and interfaces that programmers will use. The remaining sections of this User Guide present discussions of a number of important topics in J/Link programming, including how to handle exceptions and get graphics and typeset output.

When you are reading this text, or programming in Java or Mathematica, remember that the entire source code for J/Link is provided. If you want to see how anything works (or why it doesn't), you can always consult the source code directly.