JavaBlock

ReleaseJavaObject is provided mainly for developers who are writing code for others to use. Because one can never predict how one's code will be used, developers should always be sure that their code cleans up any unnecessary references it creates. Probably the most useful function for this is JavaBlock.

JavaBlock automates the process of releasing objects encountered during the evaluation of an expression. Often, a Mathematica program will need to create some Java objects with JavaNew, operate with them, perhaps causing other objects to be returned to Mathematica as the results of method calls, and finally return some result such as a number or string. Every Java object encountered by Mathematica during this operation is needed only during the lifetime of the program, much like the local variables provided in Mathematica by Block and Module, and in C, C++, Java, and many other languages by block scoping constructs (e.g., {}). JavaBlock allows you to mark a block of code as having the property that any new objects returned to Mathematica during the evaluation are to be treated as temporary, and released when JavaBlock finishes.

It is important to note that the preceding sentence said "new objects." JavaBlock will not cause every object encountered during the evaluation to be released, only those that are being encountered for the first time. Objects that have already been seen by Mathematica will not be affected. This means that you do not have to worry that JavaBlock will aggressively release an object that is not truly temporary to that evaluation.

It is not enough simply to call ReleaseJavaObject on every object you create with JavaNew, because many Java method calls return objects. You may not be interested in these return values, or you may never assign them to a named variable because they may be chained together with other calls (as in obj@returnsObject[]@foo[]), but you still need to release them. Using JavaBlock is an easy way to be sure that all novel objects are released when a block of code finishes.

JavaBlock[expr] returns whatever expr returns.

Many J/Link Mathematica programs will have the following structure:

It is very common to write a function that creates and manipulates a number of JavaObject expressions, and then returns one of them, the rest being temporary. To facilitate this, if the return value of a JavaBlock is a single JavaObject, it will not be released. This behavior is new in J/Link 2.0; in J/Link 1.x, all objects are released.

New in J/Link 2.1 is the KeepJavaObject function, which allows you to specify an object or sequence of objects that should not be released when the JavaBlock ends. Here is an example that uses this function to allow us to return a list of two objects without them being released:

MyOtherFunc[args__] :=
    Module[{obj1, obj2, obj3},
        JavaBlock[
            obj1 = JavaNew["java.awt.Frame"];
            obj2 = JavaNew["java.awt.Button"];
        obj3 = JavaNew["SomeTemporaryObject"];
        ...
        KeepJavaObject[obj1, obj2];
        {obj1, obj2}
    ]
]

BeginJavaBlock and EndJavaBlock can be used to provide the same functionality as JavaBlock across more than one evaluation. EndJavaBlock releases all novel Java objects returned to Mathematica since the previous matching BeginJavaBlock. These functions are mainly of use during development, when you might want to set a mark in your session, do some work, and then release all novel objects returned to Mathematica since that point. BeginJavaBlock and EndJavaBlock can be nested. Every BeginJavaBlock should have a matching EndJavaBlock, although it is not a serious error to forget to call EndJavaBlock, even if you have nested levels of them—you will only fail to release some objects.