Beginning JNI with NetBeans C/C++ Pack 5.5(2)

Prerequisites

This tutorial assumes you have some basic knowledge of, or programming experience with, the following technologies:

• Java programming language
• C programming language
• NetBeans IDE

Software Required for Tutorial

Before you begin, you need to install the following software on your computer:

• J2SE Development Kit (JDK™) 5.0 (download)
• NetBeans IDE 5.5 (download)
• NetBeans C/C++ Pack 5.5 (download)
• gcc, make

Notations Used in Tutorial

• <JAVA_HOME> - the JDK installation directory
• <PROJECTS_ROOT> - directory that contains the Java project you create

Tutorial Exercises

• Exercise 0: Installing and Configuring Tutorial Environment
• Exercise 1: Setting Up General Java Application Project
• Exercise 2: Setting Up C/C++ Dynamic Library Project
• Exercise 3: Building and Running Application

Configuring System

Append the paths to the directories that contain the gcc and make utilities to the PATH environment variable.

Running Software

Start the NetBeans IDE.

Creating General Java Application Project

1. Choose File > New Project. Under Categories, select General. Under Projects, select Java Application, and click Next.

   
   Figure 1

2. Under Project Name, enter HelloWorld.
3. Change the Project Location to any directory on your computer (hereinafter, this directory is referred to as <PROJECTS_ROOT>).
4. Leave the Create Main Class checkbox selected and accept the default value for the corresponding text field.

   
   Figure 2

5. Leave the Set as Main Project checkbox selected. Then click Finish.
   
   The IDE creates the <PROJECTS_ROOT>/HelloWorld project folder.

Editing Main Class Source

1. To open the Main class source in the editor, right-click the Main class node, and choose Open from the context menu.
2. Replace the body of the main method with the following:

   
           new Main().nativePrint();
                       

3. Press Alt - Enter and choose the Create method nativePrint() in helloworld.Main line from the drop-down list.
   A compilation error was caused by referencing a non-existing method in Step 2 above and the IDE automatically proposes a fix for this problem.

   
   Figure 3

4. Modify the body of the nativePrint() method by deleting its contents and inserting the native keyword into the method signature as follows:

   
           private native void nativePrint();
                       

   The native keyword indicates that the method has an implementation located in an external native library, thus the code is going to compile correctly. However at runtime the library location is not clear. Refer to the Configuring the Java Project section below for details.
5. Press Ctrl - F11 to clean and build the project.
   The project should build successfully.

Creating Native Library Header File

1. Switch to the console and navigate to the <PROJECTS_ROOT> directory.
2. Type the following:

   
           <JAVA_HOME>/bin/javah -o HelloWorldNative.h -jni
                   -classpath <PROJECTS_ROOT>/HelloWorld/build/classes helloworld.Main
                       

   
   A HelloWorldNative.h C header file is generated. It is required to provide correct function declaration for the native implementation of the nativePrint() method.
3. Switch back to the NetBeans IDE window.

Summary

In this exercise you created a new General Java Application Project, specified its location and defined the package and name of the main class of the project. You also added a new method to the main class and marked it as a method having a native implementation. As a final step we created a C header file which is required later for the native library compilation.

Creating New C/C++ Dynamic Library Project

1. Choose File > New Project. Under Categories, select C/C++ Development. Under Projects, select C/C++ Dynamic Library, and click Next.

   
   Figure 4

2. Under Project Name, type HelloWorldNative.
3. Under Project Location, type the same location as you entered for the General Java Application project, <PROJECTS_ROOT>. The required value should be already there as the default value.
4. Accept the defaults for all other fields.

   
   Figure 5

5. Leave the Set as Main Project checkbox selected. Then click Finish.
   The IDE creates the <PROJECTS_ROOT>/HelloWorldNative project folder.

Setting Project Properties

1. Right-click the project node and choose Properties from the context menu.
2. In the opened dialog box navigate to Configuration Properties > C/C++ > GNU C Compiler > General. Edit the value of the Additional Include Libraries property. Set it to be <JAVA_HOME>/include, <JAVA_HOME>/include/linux
   These settings are required to enable references to the Java jni.h library from your C code.

   
   Figure 6

3. Navigate to Configuration Properties > C/C++ > GNU C Compiler > Command Line. Edit the value of the Additional Options property. Set it to -shared -m32.
   The -shared option tells the compiler to generate a dynamic library.
   -m32 tells the compiler to create a 32-bit binary. By default on 64-bit systems the compiled binaries are 64-bit, which causes a lot of problems with 32-bit JDKs.

   
   Figure 7

4. Navigate to Configuration Properties > Linker > General. Edit the Output property value. Set it to dist/HelloWorldNative.so
   The goal of this step is to simplify the path of the resulting so file, in order to make referencing it from Java easier for you.

   
   Figure 8

5. Click OK.
   The defined settings are saved.

Adding Header File

1. Copy the generated <PROJECTS_ROOT>/HelloWorldNative.h header file to the C/C++ Library project directory, <PROJECTS_ROOT>/HelloWorldNative.
2. In the Projects view, navigate to HelloWorldNative > Source Files. Right-click the Source Files node and choose Add Existing Item from the context menu. Point the IDE to the HelloWorldNative.h file.
   The HelloWorldNative.h file appears under Source Files.

Implementing Method

1. Right-click the Source Files node and choose New > Add Empty C File from the context menu. Under File Name type HelloWorldNative, and click Finish.
   The editor opens the HelloWorldNative.c file.

   
   Figure 9

2. Edit the HelloWorldNative.c file by typing the following code:

   
           #include <jni.h>
           #include <stdio.h>
           #include "HelloWorldNative.h"
   
           JNIEXPORT void JNICALL Java_helloworld_Main_nativePrint
               (JNIEnv *env, jobject obj)
           {
               printf("\nHello World from C\n");
           }
                       

   
   Figure 10

3. Right-click the HelloWorldNative project node and choose Build Project
   The Output dialog box displays Build successful. Exit value 0.

   
   Figure 11

Summary

In this exercise you created a new C/C++ Dynamic Library, specified its location and configured it to be able to build JNI implementation of your Java method. You added the generated header file for the native method you have declared in the Java application and implemented it.

Configuring Java Project

1. Open the Main.java file in the editor.
2. Add the following initialization code:

   
           static {
               System.load("<PROJECTS_ROOT>/HelloWorldNative/dist/HelloWorldNative.so");
           }
                       

   
   Figure 12

Running Application

1. To set the HelloWorld Java project as the main project, right-click the project node and choose Set As Main Project from the context menu.
2. Press F6 to run the application.
   The program should execute correctly and the Output dialog box should say:

   
           Hello World from C
           BUILD SUCCESSFUL (total time: 0 seconds)
                           

   
   Figure 13

Summary

In this exercise you made some final configuration steps and ran the application to verify that the implementation of the native method comes from the native C library.