matrixfurry.com
The open source OpenXR runtime
1# Java Native Interface for C++
2
3## Overview
4
5JNIPP is just a C++ wrapper for the standard Java Native Interface (JNI). It
6tries to take some of the long-winded annoyance out of integrating your Java
7and C++ code.
8
9While this project has so far just been a utility library for my own usage,
10it seems to have caught the eye of some others who have also been looking for
11a suitable C++ JNI layer. If you have feature requests, do not hesitate to
12submit them as Github issues. Please be descriptive in your feature request.
13The more useful information you provide - along with justification on why it
14should be implemented - the more likely it is that I will add your feature.
15
16## Requirements
17
18To compile you will need:
19
20- A C++11 compatible compiler
21- An installation of the Java Development Kit (JDK)
22- The `JAVA_HOME` environment variable, directed to your JDK installation.
23
24## Usage
25
26> For comprehensive examples on how to use *jnipp*, see the `tests` project
27> in the project source code.
28
29There are two situations where the Java Native Interface would be needed.
30
31- A Java application calling C/C++ functions; or
32- A C/C++ application calling Java methods
33
34### Calling Java from C++
35
36The following is an example of calling Java from C++.
37
38```C++
39#include <jnipp.h>
40
41int main()
42{
43 // An instance of the Java VM needs to be created.
44 jni::Vm vm;
45
46 // Create an instance of java.lang.Integer
47 jni::Class Integer = jni::Class("java/lang/Integer");
48 jni::Object i = Integer.newInstance("1000");
49
50 // Call the `toString` method on that integer
51 std::string str = i.call<std::string>("toString");
52
53 // The Java VM is automatically destroyed when it goes out of scope.
54 return 0;
55}
56```
57
58### Calling C++ from Java
59
60Consider a basic Java program:
61
62```Java
63package com.example;
64
65class Demo {
66 public int value;
67
68 public static void main(String[] args) {
69 Demo demo = new Demo();
70 demo.value = 1000;
71 demo.run();
72 }
73
74 public native void run();
75}
76```
77
78A matching C++ library which uses *jnipp* could look like:
79
80```C++
81#include <jnipp.h>
82#include <iostream>
83
84/*
85 The signature here is defind by the JNI standard, so must be adhered to.
86 Although, to prevent pollution of the global namespace, the JNIEnv and
87 jobject types defind by the standard JNI have been placed into the
88 jni namespace.
89 */
90extern "C" void Java_com_example_Demo_run(jni::JNIEnv* env, jni::jobject obj)
91{
92 // jnipp only needs initialising once, but it doesn't hurt to do it again.
93 jni::init(env);
94
95 // Capture the supplied object.
96 jni::Object demo(obj);
97
98 // Print the contents of the `value` field to stdout.
99 std::cout << demo.get<int>("value") << std::endl;
100}
101```
102
103## Configuration
104
105By default, *jnipp* uses std::runtime_error as the base exception class. If you wish,
106you can define `JNIPP_EXCEPTION_CLASS` to be the exception class you wish to use, before
107including `jnipp.h`. It just needs a `const char*` constructor.