Contexts and Visibility of Static Members

LoadJavaClass has two options that let you control the naming and visibility of static methods and fields. To understand these options, you need to understand the problems they help to solve. We have to get a bit ahead of ourselves to explain the issues, since we have not yet discussed how to call Java methods. When a class is loaded, definitions are created in Mathematica that allow you to call methods and access fields of objects of that class. Static members are treated quite differently from nonstatic ones. None of these issues arise for nonstatic members, so we will only be discussing static members in this section. Say you have a class named com.foobar.MyClass that contains a static method named foo. When you load this class, a definition must be set up for foo so that it can be called by name, something like foo[args]. The question becomes: In what context do you want the symbol foo defined, and do you want this context to be visible (i.e., on $ContextPath)?

J/Link always creates a definition for foo in a context that mirrors its fully qualified classname: com`foobar`MyClass`foo. This is done to avoid conflicting with symbols named foo that might be present in other contexts. However, you might find it clumsy to have to call foo by typing the full context name every time, as in com`foobar`MyClass`foo[args]. The option AllowShortContext->True (this is the default setting) causes J/Link to also make definitions for foo accessible in a shortened context, one that consists of just the class name without the hierarchical package name prefix. In our example, this means that you could call foo as simply MyClass`foo[args]. If you need to avoid use of the short context because there is already a context of the same name in your Mathematica session, you can use AllowShortContext->False. This forces all names to be put only in the "deep" context. Note that even with AllowShortContext->True, names for statics are also put into the deep context, so you can always use the deep context to refer to a symbol if you desire.

AllowShortContext, then, lets you control the context where the symbol names are defined. The other option, StaticsVisible, controls whether this context is made visible (put on $ContextPath) or not. The default is StaticsVisible->False, so you have to use a context name when referring to a symbol, as in MyClass`foo[args]. With StaticsVisible->True, MyClass` will be put on $ContextPath, so you could just write foo[args]. Having the default be True would be a bit dangerous—every time you load a class a potentially large number of names would suddenly be created and made visible in your Mathematica session, opening up the possibility for all sorts of "shadowing" problems if symbols of the same names were already present. This problem is particularly acute with Java, because method and field names in Java typically begin with a lowercase letter, which is also the convention for user-defined symbols in Mathematica. Some Java classes define static methods and fields with names like x, y, width, and so on, so shadowing errors are very likely to occur (see Section 2.6.8 in The Mathematica Book for a discussion of contexts and shadowing problems).

For these reasons StaticsVisible->True is recommended only for classes that you have written, or ones whose contents you are familiar with. In such cases, it can save you some typing, make your code more readable, and prevent the all-too-easy bug of forgetting to type the package prefix. A classic example would be implementing the venerable "addtwo" MathLink example program. In Java, it might look like this:

public class AddTwo {

    public static int addtwo(int i, int j) {return i + j;}

}

With the default StaticsVisible->False, you would have to call addtwo as AddTwo`addtwo[3, 4]. Setting StaticsVisible->True lets you write the more obvious addtwo[3, 4].

Be reminded that these options are only for static methods and fields. As discussed later, nonstatics are handled in a way that makes context and visibility issues go away completely.