JNI crash course tutorial – Part 1


JNI is a knowledge anyone developing games with cocos2d-x must have. As I don’t known it enough to feel comfortable with the theme so I started studying it myself.

During my learning process I like to take notes and share what I’m discovering. This post aims to be an introductory text on JNI. I will try to teach you the basics so you can understand how it works and how to integrate your own Java / native code (C/C++).

It is essential when developing games for Android using cocos2d-x.

There are 2 scenarios when it comes to JNI:

  • Java code calling native code (C/C++)
  • Native code (C/C++) calling Java code.

Native code cannot access directly Java objects and Java variables. The other way around isn’t possible either.

You must translate Java types into native ones and vice-versa. This is done using functions provided by Java Native Interface API.

Bellow is a table showing the map between Java primitive types and C/C++ primitive types

Primitive types: There are nine primitive types in Java

Table 1 – Mapping Java and C/C++ types

Did you notice that all native types except void type are formed by the java primitive name prepended by letter j?

It worths to mention jsize (No, it’s not in the above table). The jsize integer type is used to describe cardinal indices and sizes. It’s just a typedef of jint:

Object types: There are fourteen primitive types in Java

JNI defines a bunch of reference types for some kind of Java objects. They are hierarchically organized as shown in picture 1.

Picture 1 – reference types hierarchie

C and C++ have some differences. In C, all other JNI reference types are defined as jobject.

In C++ JNI has some dummy classes to provide  the subtyping relationship.

The jvalue Value Type

It is the element type used in argument arrays. It’s defined as  the union of the reference types and primitive types as follows:

Signature types: There are eleven signature types in JNI

Table 2 – Signature types

Later I will explain the use of signature types. For now, lets practice a little bit how to map Java types into signature types.:

For example, the Java method:

boolean myMethod (String s, int[] arr, byte b);

has the following type signature:


Notice that

  • fully qualified name of a class includes its package, so String class in java is in really java.lang.String.
  • there is nothing to represent whether a method /member is static.
  • there is nothing to represent method visibility
  • “(” and “)” are used to represent a method.
  • there is no symbol to separate different parameters (like ‘,’ used in the Java method.
  • return type is the last one represented.

Note: constructors use V as return type and <init> in its name

Try to extract signature from the following methods:

You can check answers in the end of the post.

Field and Method IDs

These are regular C/C++ pointers. There definition are the following:

I will explain their use later.


Answers to proposed exercises

a) public abstract boolean isReady();
Signature: ()Z

b) private com.google.ads.d a;
Signature: Lcom/google/ads/d;

c) public static final String INTENT_ACTION_PARAM;
Signature: Ljava/lang/String;

d) public void newAdVideoView(int, int, int, int);
Signature: (IIII)V

e) private void a(com.google.ads.h, boolean, int);
Signature: (Lcom/google/ads/h;ZI)V

f) public void onActivityResult(int, int, android.content.Intent);
Signature: (IILandroid/content/Intent;)V

g) String(byte[] bytes);
Signature: ([B)V

In the next post I will write how to integrate Java and C/C++ code.

Disclaimer: I’m not an expert in JNI. I’m sharing what I’m learning in the hope it will be usefull to someone. This post is strongly based in this article and on my own experiences. Did I make a mistake? Tell me. Did you like this post? Please, use twitter, facebook and any other means available to tell your friends about it.

Please, try my games, play free on-line games on my site, tweet this post url and share it on facebook, google+ and other social medias.

This entry was posted in android, cocos2d, games and tagged , , , , , , . Bookmark the permalink.
  • daylord

    Hello… First thanks for this tutorial! But when you’ll update it with the next tutorial??

  • I still haven’t time to do it.

    At them moment I’m porting a system made with C/C++ and C# / ASP.NET (Windows) to C/C++ and Java J2EE (Linux) and this work will last until the end of November.

    After that I hope to complete the article.