Beginning JNI with NetBeans C/C++ Pack 6.0, Linux

This tutorial takes you through the creation of a sample application that uses Java^TM Native Interface (JNI) code written in the C programming language. For the part of the application written in the Java^TM programming language, you will use NetBeans IDE 6.0; for the part written in the C programming language, you will use NetBeans C/C++ Pack 6.0.

You will start off by creating a simple Java project, adding a native method to it, and then implementing this method in C using NetBeans C/C++ Pack 6.0.

Expected duration: 30 minutes

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) 6.0 (download)
• NetBeans IDE 6.0 (Download the All bundle and customize it to install the Base IDE, Java SE Pack, and C/C++ Pack) (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 the Tutorial Environment

Exercise 1: Setting Up the General Java Application Project

Exercise 2: Setting Up the C/C++ Dynamic Library Project

Exercise 3: Building and Running the Application

Exercise 0: Installing and Configuring the Tutorial Environment

This exercise will guide you through the process of performing required configuration changes that should be applied to your system prior to starting the tutorial.

Configuring the System: Append the paths to the directories that contain the gcc and make utilities to your PATH environment variable.

Running the Software: Start the NetBeans IDE.

Exercise 1: Setting Up the General Java Application Project

The goal of this exercise is to create and configure the Java part of the JNI application you will be developing. You will create a new Java application project, initialize its main class, and add a native method to this class.

Creating the General Java Application Project

1. Choose File > New Project. Under Categories, select Java. Under Projects, select Java Application. Click Next.
2. In the Project Name field, type JNIDemoJava.
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.

5. Leave the Set as Main Project checkbox selected. Then click Finish.

   The IDE creates the <PROJECTS_ROOT>/JNIDemoJava project folder.

   
   

Editing the Main Class Source

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

   new Main().nativePrint();
   

3. 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.

4. Press Ctrl-F11 to clean and build the project. The project should build successfully.

Creating the Native Library Header File

1. In a terminal window, navigate to the <PROJECTS_ROOT<> directory.
2. Type the following:

   <PROJECTS_ROOT> javah -o JNIDemoJava.h -classpath JNIDemoJava/build/classes jnidemojava.Main
   

   A JNIDemoJava.h C header file is generated. This file is required to provide a 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, you created a C header file, which is required later for the native library compilation.

Setting Up a New C/C++ Dynamic Library Project

This exercise will lead you though the process of creating the native part of the sample application. You will create the C++ Dynamic Library project and configure it to be able to build JNI code.

After you have set up the project, you will create the implementation for the native method you declared earlier in the Java part of the application.

Creating New C/C++ Dynamic Library Project

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

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

5. Leave the Set as Main Project checkbox selected. Then click Finish.

   The IDE creates the <PROJECTS_ROOT>/JNIDemoCdl-1 project folder.

   
   

Setting Project Properties

1. Right-click the project node and choose Properties.

2. In the Properties dialog box, expand the C/C++ node and the GNU C Compiler node, and select the General node. Edit the value of the Include Directories property. Set it to <JAVA_HOME>/include, <JAVA_HOME>/include/linux.

   
   
   
   

   These settings are required to enable references to the Java jni.h library from your C code.

3. Select the Command Line node. 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.

4. Expand the Linker node and select the General node.

   
   

   The goal of this step is to simplify the path of the resulting .so file, to make referencing it from Java easier for you.

5. Click OK. The defined settings are saved.

Adding a Header File

1. Copy the generated <PROJECTS_ROOT>/JNIDemoJava.h header file to the C/C++ Library project directory, <PROJECTS_ROOT>l/JNIDemoCdl-1.

2. In the Projects window, right-click the Source Files node of the JNIDemoCdl-1 project and choose Add Existing Item. Select the HelloWorldNative.h file. The JNIDemoJava.h file appears under Source Files.

   
   

Implementing a Method

1. Right-click the Source Files node and choose New >l Add Empty C File. Type JNIDemo in the File Name field, and click Finish. The editor opens the JNIDemo.c file.
2. Edit the HelloWorldNative.c file by typing the following code:

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

3. Right-click the JNIDemoCdl-1 project node and choose Build Project. The Output window displays Build successful. Exit value 0.

Summary

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

Building and Running the Application

In this exercise, you will perform some final alterations to the Java part of the application. These changes are required to ensure the Java part properly loads the native library you compiled in the previous exercise. After that you will compile and run the resulting application.

Configuring the Java Project

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

   static {
           System.load("PROJECTS_ROOT/JNIDemoCdl/dist/JNIDemoCdl.so");
          }
   

Running the Application

1. To set the JNIDemoJava Java project as the main project, right-click the project node and choose Set As Main Project.
2. Press F6 to run the application. The program should execute correctly and the Output window should display:

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

   

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.

Next Steps

You can download the sources for this tutorial from here.

You can use the following documents to get more information:

• C/C++ Support Quick Start Tutorial
• Java Native Interface