SAMPLE: How To Integrate Native Methods in a Java Application

Last reviewed: January 29, 1998
Article ID: Q161706
The information in this article applies to:
  • Microsoft Visual J++, version 1.0, 1.1
  • Microsoft SDK for Java, versions 1.5, 1.51, 2.0, 2.01

SUMMARY

The GCDJAVA sample illustrates how to use Native Methods from a Java application. This sample contains two Java classes: NativeM and Main. In the NativeM class, you define a native method called ComputeGCD. In the Main class, you define the main() function in which you instantiate an object of type NativeM to call the ComputeGCD method. The ComputeGCD method in the NativeM class is actually implemented in C language, and it calculates the greatest common factor (denominator) of two integers.

The following 27K self-extracting file is available for download from the Microsoft Software Library:

 ~ Gcdjava.exe (size: 21702 bytes) 

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q119591
   TITLE     : How to Obtain Microsoft Support Files from Online Services

MORE INFORMATION

The GCDJAVA sample contains two parts: A Java project and a DLL project. Following are the files included in the projects.

The Java project

  1. NativeM.java - contains the ComputeGCD native method. It also loads the DLL that contains the native method implementation.

  2. Main.java - the driver program that instantiates the native method class and calls the native method.

The DLL project

This project is named Native and it includes the following:

  • NativeM.h - the header file generated by msjavah and contains the native method declaration.
  • NativeM.c - contains the implementation for the native method.
  • Gcdjava.def - exports the Native method.

To use native methods in Java, you need MSJAVAH. MSJAVAH is a tool that is installed by Microsoft SDK for Java, and is available at http://www.microsoft.com/java. This tool helps you generate a header file from a Java class file. The header file generated by MSJAVAH provides a function declaration of the native method. In this sample, it is the ComputeGCD method defined in the NativeM Java class. This header file can then be used in the native language project. In this sample, it is the DLL project in C.

The following steps give a short tutorial on how to use native methods in Java:

  1. Use Visual J++ to create a Java WorkSpace.

  2. Create a Java class. For example, name it NativeM, and declare a native method called ComputeGCD. (The method definition provides only the method signature and not the implementation for it.)

  3. Create another class that defines the main() method. In this sample, we create a class named Main. In the main() function, instantiate a NativeM class object and call ComputeGCD.

  4. Add the .java files to the project WorkSpace. Please refer to NativeM.java and Main.java in the GCDJAVA project directory.

  5. Build the project, or use jvc (Java compiler) to compile the Java code you wrote in step 2.

  6. Use Msjavah.exe (this is the tool that you get from Microsoft SDK for Java available at http://www.microsoft.com/java) to create the header file.

    Msjavah.exe is installed in the Sdk-java\Bin directory. It helps create a header file from the Java class (NativeM.java) you created in step 2. The header file defines a structure that represents the Java class on the native language side and provides a function declaration for the implementation of the native method defined in that class.

    Look at the header file NativeM.h to see what is added to this file. Notice that the Native.h is included in NativeM.h. Native.h is one of the header files from the Microsoft SDK for Java. It is located in the Sdk-java\Include directory. You need to add this directory to your MSDEV environment. See step 9 below.

  7. Implement the corresponding .c file. The implementation is a regular function that is integrated with your Java class. Please refer to NativeM.c file in the Native (the DLL project) project directory.

  8. Create a new DLL project and include the .h and .c files that you created in steps 6 and 7. Also create a .def file that exports the native method. Look at Gcdjava.def file in this sample.

    NOTE: If you prefer to export functions using __declspect(dllexport) in your source code, you do not need the .def file.

  9. Make sure that you point the include files to SDK-java\Include in Tools.Options.Directories.

  10. Build the DLL. Copy the resulting DLL to the Windows\System directory.

  11. Run the Main program using jview.

If the following exception appears, then you have a library path set in your environment, but the name of the directory where your library lives is not in the environment:

    java.lang.UnsatisfiedLinkError.

Or if you get the following exception, when trying to execute this sample under Virtual Machine build 2252 or 2339 or later:

   Error: java,lang.UnsatisfiedLinkError: native.dll
   cannot load because RNIGetCompatibleVersion export not found (new
   behavior)
   Press any key to continue...

This exception occurs because several enhancements have been made to Raw Native Interface in the SDK for Java versions 2.0x, which requires many RNI DLLs, designed for earlier versions of the Microsoft Virtual Machine, to be recompiled. To identify whether an RNI DLL is compatible with the current version of the Virtual Machine, it will call the RNI DLLs RNIGetCompatibleVersion export. RNI DLLs that do not export this API will no be loaded by the current Virtual Machine.

To fix this exception , make sure you export RNIGetCompatibleVersion in the Native.def file in the DLL project. Also include its implementation in the NativeM.c file in the same DLL project:

   DWORD __cdecl RNIGetCompatibleVersion()
   {
      return RNIVER;    /* RNIVER is defined in Native.h */
   }

Rebuild the DLL. Copy the resulting DLL to the windows\system directory.

NOTE: It is also possible to access native code by creating COM objects that can be accessed via Java. There are several a couple of advantages to taking this approach:

  • By using the COM model, you make the interfacing to the Garbage Collection system transparent to the programmer. In contrast, Garbage Collection does not take place automatically when you use the Native Methods.
  • It is generally easier to reuse the COM objects in non-Java programs than Native Methods.

REFERENCES

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, see the following page on the Microsoft Technical Support site:

   http://support.microsoft.com/support/visualj/
   http://support.microsoft.com/support/java/


Additional query words: Native Code SDK

Keywords : kbcode kbsample CmdLnUtils JVM
Technology : kbInetDev
Version : 1.0 1.1
Platform : WINDOWS
Issue type : kbhowto
Solution Type : kbfile


THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Last reviewed: January 29, 1998
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.