The Microsoft way: J/Direct

The Microsoft way

At the time of this writing, Microsoft does not support JNI, but provides proprietary support to call non-Java code. This support is built into the compiler, the Microsoft JVM, and external tools. The features described in this section will work only if your program was compiled using the Microsoft Java compiler and run on the Microsoft Java Virtual Machine. If you plan to distribute your application on the Internet, or if your Intranet is built on different platforms, this can be a serious issue.

The Microsoft interface to Win32 code provides three ways to connect to Win32:

J/Direct: A way to easily call Win32 DLL functions, with some limitations.

Raw Native Interface (RNI): You can call Win32 DLL functions, but you must then handle garbage collection.

Java/COM integration: You can expose or call COM services directly from Java.

I'll cover all three techniques in the following sections.

At the time of writing, these features were tested on the Microsoft SDK for Java 2.0 beta 2, which was downloaded (with a painful process they call "Active Setup") from the Microsoft Web site. The Java SDK is a set of command-line tools, but the compilation engine can be easily plugged into the Developer Studio environment, allowing you to use Visual J++ 1.1 to compile Java 1.1 code.

J/Direct

J/Direct is the simplest way to call functions in a Win32 DLL. It was designed primarily to interface with the Win32 API, but you can use it to call any other APIs. The ease of use of this feature is counterbalanced by some limitations and reduced performance (compared to RNI). But J/Direct has distinct advantages. First, there is no need to write additional non-Java code, except the code in the DLL you want to call. In other words, you do not need a wrapper or proxy/stub DLL. Second, function arguments are automatically converted to and from standard data types. (If you must pass user-defined data types, J/Direct might not be the way to go.) Third, it's simple and straightforward, as the example below shows. In just a few lines, this example calls the Win32 API function MessageBox( ), which pops up a little modal window with a title, a message, an optional icon, and a few buttons.

Amazingly, this code is all you need to call a function in a Win32 DLL using J/Direct. The key is the @dll.import directive before the MessageBox( ) declaration, at the bottom of the example code. It looks like a comment, but it's not: it tells the compiler that the function below the directive is implemented in the USER32 DLL, and should be called accordingly. All you must do is supply a prototype that matches the function implementation in the DLL and call the function. But instead of typing in the Java version of each Win32 API function that you need, a Microsoft Java package does this for you (I'll describe this shortly). For this example to work, the function must be exported by name by the DLL, but the @dll.import directive can be used to link by ordinal as well, i.e., you can specify the entry position of the function in the DLL. I'll cover the features of the @dll.import directive later.

An important issue in the process of linking with non-Java code is the automatic marshaling of the function parameters. As you can see, the Java declaration of MessageBox( ) takes two String arguments, but the original C implementation takes two char pointers. The compiler automatically converts the standard data types for you, following the rules described in a later section.

Finally, you might have noticed the UnsatisfiedLinkError exception in the declaration of main( ). This exception occurs when the linker is unable to resolve the symbol for the non-Java function at run-time. This happens for a number of reasons: the .dll file was not found, it is not a valid DLL, or J/Direct is not supported by your virtual machine. For the DLL to be found, it must be in the Windows or WindowsSystem directory, in one of the directories listed in your PATH environment variable, or in the directory where the .class file is located. J/Direct is supported in the Microsoft Java compiler version 1.02.4213 or above, and in the Microsoft JVM version 4.79.2164 or above. To get the compiler version number, run JVC from the command line with no parameters. To get the JVM version number, locate the icon for msjava.dll, and using the context menu look at its properties.

The @dll.import directive

The @dll.import directive, your one and only way to J/Direct, is quite flexible. It has a number of modifiers that you can use to customize the way you link to the non-Java code. It can also be applied to some methods within a class or to a whole class, meaning that all of the methods you declare in that class are implemented in the same DLL. Let's look at these features.

Aliasing and linking by ordinal

For the @dll.import directive to work as shown above, the function in the DLL must be exported by name. However, you might want to use a different name than the original one in the DLL (aliasing), or the function might be exported by number (i.e. by ordinal) instead of by name. The example below declares FinestraDiMessaggio( ) (the Italian equivalent of "MessageBox") as an alias to MessageBox( ). As you can see, the syntax is pretty simple.

The next example shows how to link to a function in a DLL that is not exported by name, but by its position inside of the DLL. The example assumes that there is a DLL named MYMATH somewhere along your path, and that this DLL contains at position 3 a function that takes two integers and gives you back the sum.

You can see the only difference is the form of the entrypoint argument.

Applying @dll.import to the entire class

The @dll.import directive can be applied to an entire class, meaning that all of the methods in that class are implemented in the same DLL and with the same linkage attributes. The directive is not inherited by subclasses; for this reason, and since functions in a DLL are by nature static functions, a better design approach is to encapsulate the API functions in a separate class, as shown here:

Since the MessageBeep( ) and MessageBox( ) functions are now declared as static in a different class, you must call them specifying their scope. You might think that you must use the approach above to map all of the Win32 API (functions, constants, and data types) to Java classes. Fortunately, you don't have to.

The com.ms.win32 package

The Win32 API is fairly big - on the order of a thousand functions, constants, and data types. Of course, you do not want to write the Java equivalent of every single Win32 API function. Microsoft took care of this, distributing a Java package that maps the Win32 API to Java classes using J/Direct. This package, named com.ms.win32, is installed in your classpath during the installation of the Java SDK 2.0 if you select it in the setup options. The package is made up of large number of Java classes that reproduce the constants, data structures, and functions of the Win32 API. The three richest classes are User32.class, Kernel32.class, and Gdi32.class. These contain the core of the Win32 API. To use them, just import them in your Java code. The ShowMsgBox example above can be rewritten using com.ms.win32 as follows (I also took care of the UnsatisfiedLinkError in a more civilized way):

The package is imported in the first line. The MessageBeep( ) and MessageBox( ) functions can now be called with no other declarations. In MessageBeep( ) you can see that importing the package has also declared the Win32 constants. These constants are defined in a number of Java interfaces, all named winx (x is the first letter of the constant you want to use).

At the time of this writing, the classes in the com.ms.win32 package are still under development, but usable nonetheless.

Marshaling

Marshaling means converting a function argument from its native binary representation into some language-independent format, and then converting this generic representation into a binary format that is appropriate to the called function. In the example above, we called the MessageBox( ) function and passed it a couple of Strings. MessageBox( ) is a C function, and the binary layout of Java Strings is not the same as C strings, but the arguments are nonetheless correctly passed. That's because J/Direct takes care of converting a Java String into a C string before calling the C code. This happens with all standard Java types. Below is a table of the implicit conversions for simple data types:

The list continues, but this gives you the idea. In most cases, you do not need to worry about converting to and from simple data types, but things are different when you must pass arguments of user-defined data types. For example, you might need to pass the address of a structured, user-defined data type, or you might need to pass a pointer to a raw memory area. For these situations, there are special compiler directives to mark a Java class so that it can be passed as a pointer to a structure (the @dll.struct directive). For details on the use of these keywords, please refer to the product documentation.

Writing callback functions

Some Win32 API functions require a function pointer as one of the parameters. The Windows API function may then call the argument function, possibly at a later time when some event occurs. This technique is called a callback function. Examples include window procedures and the callbacks you set up during a print operation (you give the print spooler the address of your callback function so it can update the status and possibly interrupt printing).

Another example is the EnumWindows( ) API function that enumerates all top-level windows currently present in the system. EnumWindows( ) takes a function pointer, then traverses a list maintained internally by Windows. For every window in the list, it calls the callback function, passing the window handle as an argument to the callback.

To do the same thing in Java, you must use the Callback class in the com.ms.dll package. You inherit from Callback and override callback( ). This method will accept only int parameters and will return int or void. The method signature and implementation depends on the Windows API function that's using this callback.

Now all we need to do is create an instance of this Callback-derived class and pass it as the function pointer argument to the API function. J/Direct will take care of the rest.

The example below calls the EnumWindows( ) Win32 API; the callback( ) method in the EnumWindowsProc class gets the window handle for each top-level window, obtains the caption text, and prints it to the console window.

The call to sleep( ) allows the windows procedure to complete before main( ) exits.

Other J/Direct features

There are two more J/Direct features you can get using modifiers in the @dll.import directive. The first is simplified access to OLE functions, and the second is the selection of the ANSI versus Unicode version of API functions. Here is a short description of the two.

By convention, all OLE functions return a value of type HRESULT, which is a structured integer value defined by COM. If you program at the COM level and you want something different returned from an OLE function, you must pass it a pointer to a memory area that the function will fill with data. But in Java we don't have pointers; also, this style is not exactly elegant. With J/Direct, you can easily call OLE functions using the ole modifier in the @dll.import directive. A native method marked as an ole function is automatically translated from a Java-style method signature, which is where you decide the return type, into a COM-style function.

The second feature selects between ANSI and Unicode string handling. Most Win32 API functions that handle strings come in two versions. For example, if you look at the symbols exported by the USER32 DLL, you will not find a MessageBox( ) function, but instead MessageBoxA( ) and MessageBoxW( ) functions, which are the ANSI and Unicode version, respectively. If you do not specify which version you want to call in the @dll.import directive, the JVM will try to figure it out. But this operation takes some time during program execution time that you can save with the ansi, unicode, or auto modifiers.

For a more detailed discussion of these features, consult the Microsoft documentation.