[BAEL-4204] JNA (#10113)

* [BAEL-4203] JNA

* [BAEL-4203] JNA

java-native/README.md

@@ -0,0 +1,7 @@
+## JNI
+
+This module contains articles about the Java Native Interface (JNI).
+
+### Relevant Articles: 
+
+- [Guide to JNI (Java Native Interface)](https://www.baeldung.com/jni)

java-native/pom.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <artifactId>java-native</artifactId>
+    <name>java-native</name>
+
+    <parent>
+        <groupId>com.baeldung</groupId>
+        <artifactId>parent-modules</artifactId>
+        <version>1.0.0-SNAPSHOT</version>
+    </parent>
+
+    <properties>
+        <jna.version>5.6.0</jna.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>net.java.dev.jna</groupId>
+            <artifactId>jna-platform</artifactId>
+            <version>${jna.version}</version>
+        </dependency>
+    </dependencies>
+    
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <!-- we don't want to reuse JVMs here ! -->
+                    <reuseForks>false</reuseForks>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>

java-native/src/main/cpp/com_baeldung_jni_ExampleObjectsJNI.cpp

@@ -0,0 +1,48 @@
+#include "com_baeldung_jni_ExampleObjectsJNI.h"
+#include <iostream>
+
+/*
+ * Class:     com_baeldung_jni_ExampleObjectsJNI
+ * Method:    createUser
+ * Signature: (Ljava/lang/String;D)Lcom/baeldung/jni/UserData;
+ */
+JNIEXPORT jobject JNICALL Java_com_baeldung_jni_ExampleObjectsJNI_createUser
+  (JNIEnv *env, jobject thisObject, jstring name, jdouble balance){
+  
+    // Create the object of the class UserData
+    jclass userDataClass = env->FindClass("com/baeldung/jni/UserData");
+    jobject newUserData = env->AllocObject(userDataClass);
+	
+    // Get UserData fields to set
+    jfieldID nameField = env->GetFieldID(userDataClass , "name", "Ljava/lang/String;");
+    jfieldID balanceField = env->GetFieldID(userDataClass , "balance", "D");
+	
+    // Set the values of the new object
+    env->SetObjectField(newUserData, nameField, name);
+    env->SetDoubleField(newUserData, balanceField, balance);
+    
+    // Return the created object
+    return newUserData;
+  }
+
+/*
+ * Class:     com_baeldung_jni_ExampleObjectsJNI
+ * Method:    printUserData
+ * Signature: (Lcom/baeldung/jni/UserData;)Ljava/lang/String;
+ */
+JNIEXPORT jstring JNICALL Java_com_baeldung_jni_ExampleObjectsJNI_printUserData
+  (JNIEnv *env, jobject thisObject, jobject userData){
+  	
+  	// Find the class method id
+  	jclass userDataClass = env->GetObjectClass(userData);
+  	jmethodID methodId = env->GetMethodID(userDataClass, "getUserInfo", "()Ljava/lang/String;");
+
+    // Call the object method and get the result
+    jstring result = (jstring)env->CallObjectMethod(userData, methodId);
+	
+    // Print the result
+    std::cout << "C++: User data is: " << env->GetStringUTFChars(result, NULL) << std::endl;
+    
+    return result;
+  }
+

java-native/src/main/cpp/com_baeldung_jni_ExampleObjectsJNI.h

@@ -0,0 +1,29 @@
+/* DO NOT EDIT THIS FILE - it is machine generated */
+#include <jni.h>
+/* Header for class com_baeldung_jni_ExampleObjectsJNI */
+
+#ifndef _Included_com_baeldung_jni_ExampleObjectsJNI
+#define _Included_com_baeldung_jni_ExampleObjectsJNI
+#ifdef __cplusplus
+extern "C" {
+#endif
+/*
+ * Class:     com_baeldung_jni_ExampleObjectsJNI
+ * Method:    createUser
+ * Signature: (Ljava/lang/String;D)Lcom/baeldung/jni/UserData;
+ */
+JNIEXPORT jobject JNICALL Java_com_baeldung_jni_ExampleObjectsJNI_createUser
+  (JNIEnv *, jobject, jstring, jdouble);
+
+/*
+ * Class:     com_baeldung_jni_ExampleObjectsJNI
+ * Method:    printUserData
+ * Signature: (Lcom/baeldung/jni/UserData;)V
+ */
+JNIEXPORT jstring JNICALL Java_com_baeldung_jni_ExampleObjectsJNI_printUserData
+  (JNIEnv *, jobject, jobject);
+
+#ifdef __cplusplus
+}
+#endif
+#endif

java-native/src/main/cpp/com_baeldung_jni_ExampleParametersJNI.cpp

@@ -0,0 +1,34 @@
+#include "com_baeldung_jni_ExampleParametersJNI.h"
+#include <iostream>
+#include <string>
+
+/*
+ * Class:     com_baeldung_jni_ExampleParametersJNI
+ * Method:    sumIntegers
+ * Signature: (II)J
+ */
+JNIEXPORT jlong JNICALL Java_com_baeldung_jni_ExampleParametersJNI_sumIntegers (JNIEnv* env, jobject thisObject, jint first, jint second){
+    std::cout << "C++: The numbers received are : " << first << " and " << second << std::endl;
+    return (long)first + (long)second;
+}
+
+
+/*
+ * Class:     com_baeldung_jni_ExampleParametersJNI
+ * Method:    sayHelloToMe
+ * Signature: (Ljava/lang/String;Z)Ljava/lang/String;
+ */
+JNIEXPORT jstring JNICALL Java_com_baeldung_jni_ExampleParametersJNI_sayHelloToMe (JNIEnv* env, jobject thisObject, jstring name, jboolean isFemale){
+    const char* nameCharPointer = env->GetStringUTFChars(name, NULL);
+    std::cout << "C++: The string received is: " << nameCharPointer << std::endl;
+    std::string title;
+    if(isFemale){
+        title = "Ms. ";
+    }
+    else{
+        title = "Mr. ";
+    }
+
+    std::string fullName = title + nameCharPointer;
+    return env->NewStringUTF(fullName.c_str());
+}

java-native/src/main/cpp/com_baeldung_jni_ExampleParametersJNI.h

@@ -0,0 +1,29 @@
+/* DO NOT EDIT THIS FILE - it is machine generated */
+#include <jni.h>
+/* Header for class com_baeldung_jni_ExampleParametersJNI */
+
+#ifndef _Included_com_baeldung_jni_ExampleParametersJNI
+#define _Included_com_baeldung_jni_ExampleParametersJNI
+#ifdef __cplusplus
+extern "C" {
+#endif
+/*
+ * Class:     com_baeldung_jni_ExampleParametersJNI
+ * Method:    sumIntegers
+ * Signature: (II)J
+ */
+JNIEXPORT jlong JNICALL Java_com_baeldung_jni_ExampleParametersJNI_sumIntegers
+  (JNIEnv*, jobject, jint, jint);
+
+/*
+ * Class:     com_baeldung_jni_ExampleParametersJNI
+ * Method:    sayHelloToMe
+ * Signature: (Ljava/lang/String;Z)Ljava/lang/String;
+ */
+JNIEXPORT jstring JNICALL Java_com_baeldung_jni_ExampleParametersJNI_sayHelloToMe
+  (JNIEnv*, jobject, jstring, jboolean);
+
+#ifdef __cplusplus
+}
+#endif
+#endif

java-native/src/main/cpp/com_baeldung_jni_HelloWorldJNI.cpp

@@ -0,0 +1,13 @@
+#include "com_baeldung_jni_HelloWorldJNI.h"
+#include <iostream>
+
+/*
+ * Class:     com_baeldung_jni_HelloWorldJNI
+ * Method:    sayHello
+ * Signature: ()Ljava/lang/String;
+ */
+JNIEXPORT jstring JNICALL Java_com_baeldung_jni_HelloWorldJNI_sayHello (JNIEnv* env, jobject thisObject) {
+	std::string hello = "Hello from C++ !!";
+    std::cout << hello << std::endl;
+    return env->NewStringUTF(hello.c_str());
+}

java-native/src/main/cpp/com_baeldung_jni_HelloWorldJNI.h

@@ -0,0 +1,21 @@
+/* DO NOT EDIT THIS FILE - it is machine generated */
+#include <jni.h>
+/* Header for class com_baeldung_jni_HelloWorldJNI */
+
+#ifndef _Included_com_baeldung_jni_HelloWorldJNI
+#define _Included_com_baeldung_jni_HelloWorldJNI
+#ifdef __cplusplus
+extern "C" {
+#endif
+/*
+ * Class:     com_baeldung_jni_HelloWorldJNI
+ * Method:    sayHello
+ * Signature: ()V
+ */
+JNIEXPORT jstring JNICALL Java_com_baeldung_jni_HelloWorldJNI_sayHello
+  (JNIEnv *, jobject);
+
+#ifdef __cplusplus
+}
+#endif
+#endif

java-native/src/main/cpp/generateNativeLib.bat

@@ -0,0 +1,6 @@
+REM Create the header with javac -h . ClassName.java
+REM Remember to set your JAVA_HOME env var
+g++ -c -I%JAVA_HOME%\include -I%JAVA_HOME%\include\win32 com_baeldung_jni_HelloWorldJNI.cpp -o com_baeldung_jni_HelloWorldJNI.o
+g++ -c -I%JAVA_HOME%\include -I%JAVA_HOME%\include\win32 com_baeldung_jni_ExampleParametersJNI.cpp -o com_baeldung_jni_ExampleParametersJNI.o
+g++ -c -I%JAVA_HOME%\include -I%JAVA_HOME%\include\win32 com_baeldung_jni_ExampleObjectsJNI.cpp -o com_baeldung_jni_ExampleObjectsJNI.o
+g++ -shared -o ..\..\..\native\win32\native.dll com_baeldung_jni_HelloWorldJNI.o com_baeldung_jni_ExampleParametersJNI.o com_baeldung_jni_ExampleObjectsJNI.o -Wl,--add-stdcall-alias

java-native/src/main/cpp/generateNativeLib.sh

@@ -0,0 +1,7 @@
+# Create the header with javac -h . ClassName.java
+# Remember to set your JAVA_HOME env var
+g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/linux com_baeldung_jni_HelloWorldJNI.cpp -o com_baeldung_jni_HelloWorldJNI.o
+g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/linux com_baeldung_jni_ExampleParametersJNI.cpp -o com_baeldung_jni_ExampleParametersJNI.o
+g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/linux com_baeldung_jni_ExampleObjectsJNI.cpp -o com_baeldung_jni_ExampleObjectsJNI.o
+g++ -shared -fPIC -o ../../../native/linux_x86_64/libnative.so com_baeldung_jni_HelloWorldJNI.o com_baeldung_jni_ExampleParametersJNI.o com_baeldung_jni_ExampleObjectsJNI.o -lc
+# Don't forget to set java.library.path to point to the folder where you have the libnative you're loading.

java-native/src/main/cpp/generateNativeLibMac.sh

@@ -0,0 +1,6 @@
+# Create the header with javac -h . ClassName.java
+# Remember to set your JAVA_HOME env var
+g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/darwin com_baeldung_jni_HelloWorldJNI.cpp -o com_baeldung_jni_HelloWorldJNI.o
+g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/darwin com_baeldung_jni_ExampleParametersJNI.cpp -o com_baeldung_jni_ExampleParametersJNI.o
+g++ -c -fPIC -I${JAVA_HOME}/include -I${JAVA_HOME}/include/darwin com_baeldung_jni_ExampleObjectsJNI.cpp -o com_baeldung_jni_ExampleObjectsJNI.o
+g++ -dynamiclib -o ../../../native/macos/libnative.dylib com_baeldung_jni_HelloWorldJNI.o com_baeldung_jni_ExampleParametersJNI.o com_baeldung_jni_ExampleObjectsJNI.o -lc

java-native/src/main/java/com/baeldung/jna/CMath.java

@@ -0,0 +1,10 @@
+package com.baeldung.jna;
+
+import com.sun.jna.Library;
+import com.sun.jna.Native;
+import com.sun.jna.Platform;
+
+public interface CMath extends Library {
+    CMath INSTANCE = Native.load(Platform.isWindows() ? "msvcrt" : "c", CMath.class);
+    double cosh(double value);
+}

java-native/src/main/java/com/baeldung/jna/Main.java

@@ -0,0 +1,8 @@
+package com.baeldung.jna;
+
+public class Main {
+	
+	public static void main(String[] args) {
+		
+	}
+}

java-native/src/main/java/com/baeldung/jna/NativeFS.java

@@ -0,0 +1,46 @@
+package com.baeldung.jna;
+
+import java.util.Collections;
+import java.util.Map;
+
+import com.sun.jna.FunctionMapper;
+import com.sun.jna.LastErrorException;
+import com.sun.jna.Library;
+import com.sun.jna.Native;
+import com.sun.jna.NativeLong;
+import com.sun.jna.Platform;
+import com.sun.jna.Structure;
+import com.sun.jna.Structure.FieldOrder;
+
+public interface NativeFS extends Library {
+    
+    FunctionMapper mapper = (library,method) -> {
+        if (Platform.isWindows()) {
+            return "_" + method.getName();
+        }
+        else {
+            return "__x" + method.getName(); // On Linux, stat is actually _xstat
+        }
+    };
+    
+    public NativeFS INSTANCE = Native.load(Platform.isWindows() ? "msvcrt" : "c",
+      NativeFS.class,
+      Collections.singletonMap(Library.OPTION_FUNCTION_MAPPER, mapper));
+
+    int stat(String path, Stat stat) throws LastErrorException;
+
+    @FieldOrder({"st_dev","st_ino","st_mode","st_nlink","st_uid","st_gid","st_rdev","st_size","st_atime","st_mtime","st_ctime"})
+    public class Stat extends Structure {
+        public int st_dev;
+        public int st_ino;
+        public short st_mode;
+        public short st_nlink;
+        public short st_uid;
+        public short st_gid;
+        public int st_rdev;
+        public NativeLong st_size;
+        public NativeLong st_atime;
+        public NativeLong st_mtime;
+        public NativeLong st_ctime;
+    }
+}

java-native/src/main/java/com/baeldung/jna/StdC.java

@@ -0,0 +1,17 @@
+package com.baeldung.jna;
+
+import com.sun.jna.LastErrorException;
+import com.sun.jna.Library;
+import com.sun.jna.Native;
+import com.sun.jna.Platform;
+import com.sun.jna.Pointer;
+
+public interface StdC extends Library {
+    StdC INSTANCE = Native.load(Platform.isWindows() ? "msvcrt" : "c", StdC.class );
+    Pointer malloc(long n);
+    void free(Pointer p);
+    Pointer memset(Pointer p, int c, long n);
+    int open(String path, int flags) throws LastErrorException;
+    int close(int fd) throws LastErrorException;
+}
+

java-native/src/main/java/com/baeldung/jni/ExampleObjectsJNI.java

@@ -0,0 +1,19 @@
+package com.baeldung.jni;
+
+public class ExampleObjectsJNI {
+
+    static {
+        System.loadLibrary("native");
+    }
+    
+    public static void main(String[] args) {
+        ExampleObjectsJNI instance = new ExampleObjectsJNI();
+        UserData newUser = instance.createUser("John Doe", 450.67);
+        instance.printUserData(newUser);
+    }
+    
+    public native UserData createUser(String name, double balance);
+    
+    public native String printUserData(UserData user);
+
+}

java-native/src/main/java/com/baeldung/jni/ExampleParametersJNI.java

@@ -0,0 +1,20 @@
+package com.baeldung.jni;
+
+public class ExampleParametersJNI {
+
+    static {
+        System.loadLibrary("native");
+    }
+    
+    public static void main(String[] args) {  
+        System.out.println("Java: My full name: " + new ExampleParametersJNI().sayHelloToMe("Martin", false));
+        long sumFromNative = new ExampleParametersJNI().sumIntegers(456, 44);
+        System.out.println("Java: The sum coming from native code is: " + sumFromNative);
+    }
+    
+    // Declare another method sumIntegers that receives two integers and return a long with the sum
+    public native long sumIntegers(int first, int second);
+    
+    // Declare another method sayHelloToMe that receives the name and gender and returns the proper salutation
+    public native String sayHelloToMe(String name, boolean isFemale);
+}

java-native/src/main/java/com/baeldung/jni/HelloWorldJNI.java

@@ -0,0 +1,15 @@
+package com.baeldung.jni;
+
+public class HelloWorldJNI {
+
+    static {
+        System.loadLibrary("native");
+    }
+    
+    public static void main(String[] args) {
+        new HelloWorldJNI().sayHello();
+    }
+
+    // Declare a native method sayHello() that receives no arguments and returns void
+    public native String sayHello();
+}

java-native/src/main/java/com/baeldung/jni/UserData.java

@@ -0,0 +1,11 @@
+package com.baeldung.jni;
+
+public class UserData {
+    
+    public String name;
+    public double balance;
+    
+    public String getUserInfo() {
+        return "[name]=" + name + ", [balance]=" + balance;
+    }
+}

java-native/src/main/resources/logback.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
+            </pattern>
+        </encoder>
+    </appender>
+
+    <root level="INFO">
+        <appender-ref ref="STDOUT" />
+    </root>
+</configuration>

java-native/src/test/java/com/baeldung/jna/CMathUnitTest.java

@@ -0,0 +1,18 @@
+package com.baeldung.jna;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.jupiter.api.Test;
+
+import com.sun.jna.Native;
+import com.sun.jna.Platform;
+
+class CMathUnitTest {
+    @Test
+    void whenCallNative_thenSuccess() {
+        CMath lib = Native.load(Platform.isWindows() ? "msvcrt" : "c", CMath.class);
+        double result = lib.cosh(0);
+        assertEquals(1.0,result);
+    }
+
+}

java-native/src/test/java/com/baeldung/jna/NativeFSUnitTest.java

@@ -0,0 +1,38 @@
+package com.baeldung.jna;
+
+import static org.junit.Assert.fail;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+
+import org.junit.jupiter.api.Test;
+
+import com.baeldung.jna.NativeFS.Stat;
+import com.sun.jna.LastErrorException;
+import com.sun.jna.Platform;
+
+public class NativeFSUnitTest {
+    
+
+    @Test
+    public void whenCallNative_thenSuccess() throws IOException {
+        NativeFS lib = NativeFS.INSTANCE;
+        
+        File f = Files.createTempFile("junit", ".bin").toFile(); 
+        f.deleteOnExit();
+        Stat stat = new Stat();
+        try {
+            if (Platform.isWindows()) {
+                int rc = lib.stat(f.getAbsolutePath(), stat);
+                assertEquals(0, rc);
+                assertEquals(0,stat.st_size.longValue());
+            }
+        }
+        catch(LastErrorException error) {
+            fail("stat failed: error code=" + error.getErrorCode());
+        }
+        
+    }
+}

java-native/src/test/java/com/baeldung/jna/StdCUnitTest.java

@@ -0,0 +1,47 @@
+package com.baeldung.jna;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import org.junit.BeforeClass;
+import org.junit.jupiter.api.Test;
+
+import com.sun.jna.Native;
+import com.sun.jna.Platform;
+import com.sun.jna.Pointer;
+
+class StdCUnitTest {
+    
+    @BeforeClass
+    public static void setupProtectedMode() {
+        Native.setProtected(true);
+    }
+
+    @Test
+    public void whenMalloc_thenSuccess() {
+        StdC lib = StdC.INSTANCE;
+        Pointer p = lib.malloc(1024);
+        p.setMemory(0l, 1024l, (byte) 0);
+        lib.free(p);
+    }
+    
+    @Test
+    public void whenAccessViolation_thenShouldThrowError() {
+        // Running this test on Linux requires additional setup using libjsig.so
+        // Details here: http://java-native-access.github.io/jna/5.6.0/javadoc/overview-summary.html#crash-protection
+        // IMPORTANT NOTICE: Code for illustration purposes only. DON'T DO THIS IN YOUR OWN CODE
+        if ( Platform.isWindows()) {
+            Error e = null;
+            Pointer p = new Pointer(0l);
+            
+            try {
+                p.setMemory(0, 100*1024, (byte) 0);
+            }
+            catch(Error err) {
+                e = err;
+            }
+            
+            assertNotNull(e, "Should throw Error");
+        }
+    }
+
+}

java-native/src/test/java/com/baeldung/jni/JNINativeManualTest.java

@@ -0,0 +1,58 @@
+package com.baeldung.jni;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+
+import org.junit.Before;
+import org.junit.Test;
+
+public class JNINativeManualTest {
+    
+    @Before
+    public void setup() {
+        System.loadLibrary("native");
+    }
+    
+    @Test
+    public void whenNativeHelloWorld_thenOutputIsAsExpected() {
+        HelloWorldJNI helloWorld = new HelloWorldJNI();
+        String helloFromNative = helloWorld.sayHello();
+        assertTrue(!helloFromNative.isEmpty() && helloFromNative.equals("Hello from C++ !!"));
+    }
+    
+    @Test
+    public void whenSumNative_thenResultIsArithmeticallyCorrect() {
+        ExampleParametersJNI parametersNativeMethods = new ExampleParametersJNI();
+        assertTrue(parametersNativeMethods.sumIntegers(200, 400) == 600L);
+    }
+    
+    @Test
+    public void whenSayingNativeHelloToMe_thenResultIsAsExpected() {
+        ExampleParametersJNI parametersNativeMethods = new ExampleParametersJNI();
+        assertEquals(parametersNativeMethods.sayHelloToMe("Orange", true), "Ms. Orange");
+    }
+
+    @Test
+    public void whenCreatingNativeObject_thenObjectIsNotNullAndHasCorrectData() {
+        String name = "Iker Casillas";
+        double balance = 2378.78;
+        ExampleObjectsJNI objectsNativeMethods = new ExampleObjectsJNI();
+        UserData userFromNative = objectsNativeMethods.createUser(name, balance);
+        assertNotNull(userFromNative);
+        assertEquals(userFromNative.name, name);
+        assertTrue(userFromNative.balance == balance);
+    }
+    
+    @Test
+    public void whenNativeCallingObjectMethod_thenResultIsAsExpected() {
+        String name = "Sergio Ramos";
+        double balance = 666.77;
+        ExampleObjectsJNI objectsNativeMethods = new ExampleObjectsJNI();
+        UserData userData = new UserData();
+        userData.name = name;
+        userData.balance = balance;
+        assertEquals(objectsNativeMethods.printUserData(userData), "[name]=" + name + ", [balance]=" + balance);
+    }
+    
+}