// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= Beginning JNI with NetBeans IDE and C/C++ Plugin on Linux
:jbake-type: tutorial
:jbake-tags: tutorials 
:jbake-status: published
:icons: font
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:description: Beginning JNI with NetBeans IDE and C/C++ Plugin on Linux - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, Beginning JNI with NetBeans IDE and C/C++ Plugin on Linux

_March 2014_ [Revision number: V8.0-1]

This tutorial takes you through the creation of a simple application that uses Java^TM^ Native Interface (JNI) code written in the C programming language.

The tutorial is specific to Linux.

== Requirements

*To follow this tutorial, you need the following software and resources.*

|===
|Software or Resource |Version Required 

|NetBeans IDE |link:https://netbeans.org/downloads/index.html[+version 7.4 or 8.0 with NetBeans C/C++ plugin+] 

|Java Developer Kit (JDK) |link:http://www.oracle.com/technetwork/java/javase/downloads/index.html[+version 7 or 8+] 

|C and C++ compilers,  ``make`` ,  ``gdb``  |link:../../../community/releases/80/cpp-setup-instructions.html[+ Configuring the NetBeans IDE for C/C++/Fortran+] 
|===

See the link:../../../community/releases/80/install.html[+NetBeans IDE 8.0 Installation Instructions+] and link:../../../community/releases/80/cpp-setup-instructions.html[+ Configuring the NetBeans IDE for C/C++/Fortran+] for information on downloading and installing the required software.


== Setting Up Your Environment for the Tutorial

You need both Java modules and C/C++ modules for this tutorial. If you already have downloaded the NetBeans IDE C/C++ bundle, you can download the additional Java modules separately.

To determine if you have the Java and C/C++ modules, select File > New Project. The project categories should include both Java and C/C++.

*To download Java and C/C++ modules that may be missing:*

1. In the NetBeans IDE, select Tools > Plugins.
2. In the Available Plugins tab, select the checkbox for Java or C/C++, depending on which is missing from your IDE. If you already have the plugins, they will be listed in the Installed tab.
3. Click Install.
4. Click Next in the NetBeans IDE Installer dialog box, accept the license terms checkbox, and click Install.
5. Click Finish when the installation is complete.


== Setting Up the Java Application Project

This program requires a Java project and a C project. In this section, you will create and configure the Java project for 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.

1. Choose File > New Project. Select the Java category and Java Application project type. Click Next.
image::images/jni-new-project-java.png[]

[start=2]
. In the Project Name field, type  ``JNIDemoJava`` .

[start=3]
. You can change the Project Location to any directory on your computer, but here we use the default NetBeansProjects in the user directory.

[start=4]
. Leave the Create Main Class checkbox selected and change the Main class name to  ``jnidemojava.Main`` .

image::images/jni-new-java-app.png[]

[start=5]
. Click Finish. 

The IDE creates the  ``NetBeansProjects/JNIDemoJava``  project folder.


=== Editing the Main Class Source

1. To open the Main class source in the editor, right-click the  ``Main.java``  class node and choose Open.
2. Replace the line  ``//TODO code application logic here``  in the  ``main``  method with the following:

[source,java]
----

new Main().nativePrint();
----

[start=3]
. Notice the indicator in the left margin showing an error and lightbulb. Click on the indicator, and you are prompted with a shortcut to create the method  ``nativePrint`` .

[start=4]
. Click on this shortcut and the IDE inserts the following code:

[source,java]
----

private void nativePrint() {
      throw new UnsupportedOperationException("Not supported yet");
   }
----

[start=5]
. Delete the line

[source,java]
----

throw new UnsupportedOperationException("Not supported yet");
----

[start=6]
. Modify the  ``nativePrint()``  method by inserting the  ``native``  keyword into the method signature so that it now looks as follows:

[source,java]
----

private native void nativePrint();
----

The  ``native``  keyword indicates that the method has an implementation located in an external native library. However, at runtime the library location is not clear.

The new main method should look as follows:


[source,java]
----

public static void main(String[] args) {
       new Main().nativePrint();
   }

   private native void nativePrint();
}
----

[start=7]
. Right-click the project name and select Clean and Build. The project should build successfully.


=== Creating the Native Library Header File

In this section we use  ``javah`` , a Java tool that creates a C header from a Java class.

1. In a terminal window, navigate to the  ``NetBeansProjects``  directory.
2. Type the following:

[source,java]
----

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

----

A  ``JNIDemoJava.h``  C header file is generated in the NetBeansProjects directory. This file is required to provide a correct function declaration for the native implementation of the  ``nativePrint()``  method. You will need it later when you create the C part of this application.


[start=3]
. Switch back to the NetBeans IDE window.

*Summary*

In this exercise you created a new 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 section shows you how to create the native part of the 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.

1. Choose File > New Project. Under Categories, select C/C++. Under Projects, select C/C++ Dynamic Library. Click Next. 
image::images/jni-new-project-c.png[]

[start=2]
. In the Project Name field, type  ``JNIDemoCdl`` .

[start=3]
. In the Project Location field, use the same location that you used for the Java application project,  ``NetBeansProjects`` . The location should be shown as the default value.

[start=4]
. Accept the defaults for all other fields and click Finish.

The IDE creates the  ``NetBeansProjects/JNIDemoCdl``  project folder.


=== Setting Project Properties

1. Right-click the JNIDemoCdl project node and choose Properties.
2. In the Properties dialog box, select the C Compiler node under the Build properties.
3. Click the Include Directories and Headers ... button and click Add in the Include Directories and Headers dialog box.
4. Browse into your JDK directory, and select the  ``include``  subdirectory.
5. Select the Store path as Absolute option, then click Select to add this directory to the project's Include Directories.
6. Add the JDK's  ``include/linux``  directory in the same way, then click OK. 
image::images/jni-include-directories.png[]

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


[start=7]
. Find the Compilation Line area of the C Compiler options. Click in the text field of the Additional Options property and type  ``-shared -m32`` . image::images/jni-project-properties-cmd-options.png[]

The  ``-shared``  option tells the compiler to generate a dynamic library.
The  ``-m32``  option 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.


[start=8]
. Click the Linker category in the left panel.

[start=9]
. Click the Output text field, and replace the string

[source,java]
----

${CND_DISTDIR}/${CND_CONF}/${CND_PLATFORM}/libJNIDemoCdl.so
----
with the string

[source,java]
----

dist/libJNIDemoCdl.so
----
to simplify the path of the resulting shared object file. This will make the file easer to reference from Java.
image::images/jni-project-properties-linker.png[]

[start=10]
. Click OK. The defined settings are saved.


=== Adding a Header File

1. Go to a terminal window and move the  ``JNIDemoJava.h``  header file that you generated previously from your  ``NetBeansProjects``  directory to the C/C++ Library project directory,  ``NetBeansProjects/JNIDemoCdl`` .
2. 
In the Projects window, right-click the Header Files node of the  ``JNIDemoCdl``  project and choose Add Existing Item. Navigate to the  ``NetBeansProjects/JNIDemoCdl``  directory and select the  ``JNIDemoJava.h``  file, then click Select.

The  ``JNIDemoJava.h``  file appears under Header Files.

image::images/jni-source-files-include-file.png[]


=== Implementing a Method

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

[source,c]
----

#include <jni.h>
#include <stdio.h>
#include "JNIDemoJava.h"

JNIEXPORT void JNICALL Java_jnidemojava_Main_nativePrint
        (JNIEnv *env, jobject obj)
{

    printf("\nHello World from C\n");

}

----

[start=3]
. Save the  ``JNIDemo.c``  file.

[start=4]
. Right-click the  ``JNIDemoCdl``  project node and choose Build. The Output window displays  ``BUILD SUCCESSFUL (total time 171ms)``  or similar.

*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 for the C++ dynamic library after the  ``public class Main``  line, using the path to the output file that you shortened in the previous exercise:

[source,java]
----

static {
        System.load("_full-path-to-NetBeansProjects-dir_/JNIDemoCdl/dist/libJNIDemoCdl.so");
       }

----
Replace _full-path-to-NetBeansProjects-dir_ with the path to your NetBeansProjects directory, which should be something similar to  ``/home/_username_/NetBeansProjects`` 

[start=3]
. Save the  ``Main.java``  file.


=== Running the JNIDemoJava Application

1. Select the JNIDemoJava application in the Projects window.
2. Press F6 or click the Run button in the toolbar to run the application. The program should execute correctly and the Output window should display output similar to the following: 
image::images/jni-build-success.png[]


=== 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

If you want to check your work against a working example, you can link:https://netbeans.org/projects/samples/downloads/download/Samples%252FCPlusPlus%252FJNIDemo.zip[+ download a zip file containing the source code+] from netbeans.org.

You can use the following documents to get more information:

* link:quickstart.html[+ C/C++ Projects Quick Start Tutorial+]
* link:http://docs.oracle.com/javase/7/docs/technotes/guides/jni/[+JNI Specification+]
* link:http://en.wikipedia.org/wiki/Java_Native_Interface[+Java Native Interface+]
link:https://netbeans.org/about/contact_form.html?to=7&subject=Feedback:%20Beginning%20JNI%20with%20NetBeans%20IDE%20and%20C/C++%20Plugin%20on%20Linux[+Send Feedback on This Tutorial+]