JNIpp 1.0
JNI meets C++
jni Namespace Reference

Contains Java Native Interface functions. More...

Classes

class  AbstractObject
 Abstract Java object (jobject) container. More...
class  LObject
 Wrapper for local Java objects. More...
class  VarArgs
 Information about vararg support in jni functions. More...

Enumerations

enum  ArrayReleaseMode { CommitFreeElements, CommitElements, FreeElements }
 Release mode for ReleaseXXXArrayElements functions. More...

Functions

JNIEnv * GetEnv ()
 Returns JNIEnv* for the current thread.
void Initialize (JavaVM *vm)
 Initializes jni; must be called before any other jni function.
void Initialize (JNIEnv *env)
 Version of Initialize(JavaVM*) that takes JNIEnv*.
void FatalError (const char *message,...)
 Terminates current program with a message.
LObject FindClass (const char *name)
 Finds class by name.
LObject GetObjectClass (const AbstractObject &object)
 Returns class of the object.
LObject GetSuperclass (const AbstractObject &clazz)
 Returns superclass of the clazz.
bool IsAssignableFrom (const AbstractObject &clazz, const AbstractObject &clazzFrom)
 Returns true if object of type clazz can be safely cast to clazzFrom.
bool IsInstanceOf (const AbstractObject &object, const AbstractObject &clazz)
 Returns true if object is an instance of clazz.
bool IsSameObject (const AbstractObject &object1, const AbstractObject &object2)
 Tests whether two references refer to the same Java object.
void Throw (const AbstractObject &throwable)
 Raises Java exception.
void TranslateJavaException ()
 Converts currently pending Java exception to C++ exception.
void TranslateCppException ()
 Converts current C++ exception to the Java exception and raises it using jni::Throw().
jsize GetArrayLength (const AbstractObject &array)
 Returns array's length.
LObject NewObjectArray (jsize length, const AbstractObject &elementClass)
 Creates new object array and fills it with nulls.
LObject NewObjectArray (jsize length, const AbstractObject &elementClass, const AbstractObject &initialElement)
 Creates new object array of objects and fills it with initialElement.
LObject GetObjectArrayElement (const AbstractObject &array, jsize index)
 Retrieves object array element.
void SetObjectArrayElement (const AbstractObject &array, jsize index, const AbstractObject &value)
 Sets object array element.
LObject NewBoolArray (jsize length)
 Creates new boolean array; equivalent to jni::NewBooleanArray().
bool * GetBoolArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks boolean array elements.
void ReleaseBoolArrayElements (const AbstractObject &array, bool *elements, jint mode)
 Releases (and optionally commits) boolean array elements.
void GetBoolArrayRegion (const AbstractObject &array, jsize start, jsize length, bool *buffer)
 Retrieves region from boolean array.
void SetBoolArrayRegion (const AbstractObject &array, jsize start, jsize length, const bool *buffer)
 Updates region in boolean array.
LObject NewBooleanArray (jsize length)
 Creates new boolean array.
jboolean * GetBooleanArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks boolean array elements; see also jni::GetBoolArrayElements().
void ReleaseBooleanArrayElements (const AbstractObject &array, jboolean *elements, ArrayReleaseMode mode)
 Releases (and optionally commits) boolean array elements; see also jni::ReleaseBoolArrayElements().
void GetBooleanArrayRegion (const AbstractObject &array, jsize start, jsize length, jboolean *buffer)
 Retrieves region from boolean array; see also jni::GetBoolArrayRegion().
void SetBooleanArrayRegion (const AbstractObject &array, jsize start, jsize length, const jboolean *buffer)
 Updates region in boolean array; see also jni::SetBoolArrayRegion().
LObject NewByteArray (jsize length)
 Creates new byte array.
jbyte * GetByteArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks byte array elements.
void ReleaseByteArrayElements (const AbstractObject &array, jbyte *elements, ArrayReleaseMode mode)
 Releases (and optionally commits) byte array elements.
void GetByteArrayRegion (const AbstractObject &array, jsize start, jsize length, jbyte *buffer)
 Retrieves region from byte array.
void SetByteArrayRegion (const AbstractObject &array, jsize start, jsize length, const jbyte *buffer)
 Updates region in byte array.
LObject NewCharArray (jsize length)
 Creates new char array.
jchar * GetCharArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks char array elements.
void ReleaseCharArrayElements (const AbstractObject &array, jchar *elements, ArrayReleaseMode mode)
 Releases (and optionally commits) char array elements.
void GetCharArrayRegion (const AbstractObject &array, jsize start, jsize length, jchar *buffer)
 Retrieves region from char array.
void SetCharArrayRegion (const AbstractObject &array, jsize start, jsize length, const jchar *buffer)
 Updates region in char array.
LObject NewShortArray (jsize length)
 Creates new short array.
jshort * GetShortArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks short array elements.
void ReleaseShortArrayElements (const AbstractObject &array, jshort *elements, ArrayReleaseMode mode)
 Releases (and optionally commits) short array elements.
void GetShortArrayRegion (const AbstractObject &array, jsize start, jsize length, jshort *buffer)
 Retrieves region from short array.
void SetShortArrayRegion (const AbstractObject &array, jsize start, jsize length, const jshort *buffer)
 Updates region in short array.
LObject NewIntArray (jsize length)
 Creates new int array.
jint * GetIntArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks int array elements.
void ReleaseIntArrayElements (const AbstractObject &array, jint *elements, ArrayReleaseMode mode)
 Releases (and optionally commits) int array elements.
void GetIntArrayRegion (const AbstractObject &array, jsize start, jsize length, jint *buffer)
 Retrieves region from int array.
void SetIntArrayRegion (const AbstractObject &array, jsize start, jsize length, const jint *buffer)
 Updates region in int array.
LObject NewLongArray (jsize length)
 Creates new long array.
jlong * GetLongArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks long array elements.
void ReleaseLongArrayElements (const AbstractObject &array, jlong *elements, ArrayReleaseMode mode)
 Releases (and optionally commits) long array elements.
void GetLongArrayRegion (const AbstractObject &array, jsize start, jsize length, jlong *buffer)
 Retrieves region from long array.
void SetLongArrayRegion (const AbstractObject &array, jsize start, jsize length, const jlong *buffer)
 Updates region in long array.
LObject NewFloatArray (jsize length)
 Creates new float array.
jfloat * GetFloatArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks float array elements.
void ReleaseFloatArrayElements (const AbstractObject &array, jfloat *elements, ArrayReleaseMode mode)
 Releases (and optionally commits) float array elements.
void GetFloatArrayRegion (const AbstractObject &array, jsize start, jsize length, jfloat *buffer)
 Retrieves region from float array.
void SetFloatArrayRegion (const AbstractObject &array, jsize start, jsize length, const jfloat *buffer)
 Updates region in float array.
LObject NewDoubleArray (jsize length)
 Creates new double array.
jdouble * GetDoubleArrayElements (const AbstractObject &array, bool *isCopy=0)
 Retrieves and locks double array elements.
void ReleaseDoubleArrayElements (const AbstractObject &array, jdouble *elements, ArrayReleaseMode mode)
 Releases (and optionally commits) double array elements.
void GetDoubleArrayRegion (const AbstractObject &array, jsize start, jsize length, jdouble *buffer)
 Retrieves region from double array.
void SetDoubleArrayRegion (const AbstractObject &array, jsize start, jsize length, const jdouble *buffer)
 Updates region in double array.
jmethodID GetMethodID (const AbstractObject &clazz, const char *name, const char *signature)
 Finds method in the class.
jmethodID GetStaticMethodID (const AbstractObject &clazz, const char *name, const char *signature)
 Finds static method in the class.
LObject NewObject (const AbstractObject &clazz, jmethodID constructorID, VarArgs)
 Create new Java object (equivalent to new in Java).
void CallVoidMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls void method.
LObject CallObjectMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning object.
jboolean CallBooleanMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning boolean; see also CallBoolMethod().
bool CallBoolMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning boolean and converts result to C++ bool.
jbyte CallByteMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning byte.
jchar CallCharMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning char.
jshort CallShortMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning short.
jint CallIntMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning int.
jlong CallLongMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning long.
jfloat CallFloatMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning float.
jdouble CallDoubleMethod (const AbstractObject &object, jmethodID methodID, VarArgs)
 Calls method returning double.
void CallNonvirtualVoidMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls void method defined in clazz.
LObject CallNonvirtualObjectMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning object defined in clazz.
jboolean CallNonvirtualBooleanMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning boolean; see also CallNonvirtualBoolMethod().
bool CallNonvirtualBoolMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning boolean defined in clazz and converts result to C++ bool.
jbyte CallNonvirtualByteMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning byte defined in clazz.
jchar CallNonvirtualCharMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning char defined in clazz.
jshort CallNonvirtualShortMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning short defined in clazz.
jint CallNonvirtualIntMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning int defined in clazz.
jlong CallNonvirtualLongMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning long defined in clazz.
jfloat CallNonvirtualFloatMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning float defined in clazz.
jdouble CallNonvirtualDoubleMethod (const AbstractObject &object, const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls method returning double defined in clazz.
void CallStaticVoidMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls void static method.
jobject CallStaticObjectMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning object.
jboolean CallStaticBooleanMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning boolean; see also CallStaticBoolMethod().
bool CallStaticBoolMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning boolean and converts result to C++ bool.
jbyte CallStaticByteMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning byte.
jchar CallStaticCharMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning char.
jshort CallStaticShortMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning short.
jint CallStaticIntMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning int.
jlong CallStaticLongMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning long.
jfloat CallStaticFloatMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning float.
jdouble CallStaticDoubleMethod (const AbstractObject &clazz, jmethodID methodID, VarArgs)
 Calls static method returning double.
jfieldID GetFieldID (const AbstractObject &clazz, const char *name, const char *signature)
 Returns id of the field.
jfieldID GetStaticFieldID (const AbstractObject &clazz, const char *name, const char *signature)
 Returns id of the static field.
LObject GetObjectField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of an object field.
void SetObjectField (const AbstractObject &object, jfieldID fieldID, const AbstractObject &value)
 Sets value to an object field.
jboolean GetBooleanField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a boolean field; see also GetBoolField().
void SetBooleanField (const AbstractObject &object, jfieldID fieldID, jboolean value)
 Sets value to a boolean field; see also SetBoolField().
bool GetBoolField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a boolean field and converts it to C++ bool.
void SetBoolField (const AbstractObject &object, jfieldID fieldID, bool value)
 Sets value of a C++ bool to a boolean field.
jbyte GetByteField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a byte field.
void SetByteField (const AbstractObject &object, jfieldID fieldID, jbyte value)
 Sets value to a byte field.
jchar GetCharField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a char field.
void SetCharField (const AbstractObject &object, jfieldID fieldID, jchar value)
 Sets value to a char field.
jshort GetShortField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a short field.
void SetShortField (const AbstractObject &object, jfieldID fieldID, jshort value)
 Sets value to a short field.
jint GetIntField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a int field.
void SetIntField (const AbstractObject &object, jfieldID fieldID, jint value)
 Sets value to a int field.
jlong GetLongField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a long field.
void SetLongField (const AbstractObject &object, jfieldID fieldID, jlong value)
 Sets value to a long field.
jfloat GetFloatField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a float field.
void SetFloatField (const AbstractObject &object, jfieldID fieldID, jfloat value)
 Sets value to a float field.
jdouble GetDoubleField (const AbstractObject &object, jfieldID fieldID)
 Retrieves value of a double field.
void SetDoubleField (const AbstractObject &object, jfieldID fieldID, jdouble value)
 Sets value to a double field.
LObject GetStaticObjectField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a static object field.
void SetStaticObjectField (const AbstractObject &clazz, jfieldID fieldID, const AbstractObject &value)
 Sets value to a static object field.
jboolean GetStaticBooleanField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a boolean field; see also GetStaticBoolField.
void SetStaticBooleanField (const AbstractObject &clazz, jfieldID fieldID, jboolean value)
 Sets value to a static boolean field; see also SetStaticBoolField.
bool GetStaticBoolField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a boolean field and converts it to C++ bool.
void SetStaticBoolField (const AbstractObject &clazz, jfieldID fieldID, bool value)
 Sets value of a C++ bool to a static boolean field.
jbyte GetStaticByteField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a static byte field.
void SetStaticByteField (const AbstractObject &clazz, jfieldID fieldID, jbyte value)
 Sets value to a static byte field.
jchar GetStaticCharField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a static char field.
void SetStaticCharField (const AbstractObject &clazz, jfieldID fieldID, jchar value)
 Sets value to a static char field.
jshort GetStaticShortField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a static short field.
void SetStaticShortField (const AbstractObject &clazz, jfieldID fieldID, jshort value)
 Sets value to a static short field.
jint GetStaticIntField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a static int field.
void SetStaticIntField (const AbstractObject &clazz, jfieldID fieldID, jint value)
 Sets value to a static int field.
jlong GetStaticLongField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a static long field.
void SetStaticLongField (const AbstractObject &clazz, jfieldID fieldID, jlong value)
 Sets value to a static long field.
jfloat GetStaticFloatField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a static float field.
void SetStaticFloatField (const AbstractObject &clazz, jfieldID fieldID, jfloat value)
 Sets value to a static float field.
jdouble GetStaticDoubleField (const AbstractObject &clazz, jfieldID fieldID)
 Retrieves value of a static double field.
void SetStaticDoubleField (const AbstractObject &clazz, jfieldID fieldID, jdouble value)
 Sets value to a static double field.

Variables

LObject NullObject
 Pass this object instead of NULL.
const bool JBooleanIsBool
 Indicates whether an array of jboolean values can be cast to an array of C++ bool values.

Detailed Description

Contains Java Native Interface functions.

Functions in this namespace are modified versions of standard JNI functions found in jni.h and described in JNI specification at http://java.sun.com/docs/books/jni/.

Overview of modifications:

  • Functions don't take JNIEnv* pointer. They get it from the current thread using jni::GetEnv().

Enumeration Type Documentation

Release mode for ReleaseXXXArrayElements functions.

Enumerator:
CommitFreeElements 

Copy back the content and free the elements buffer.

CommitElements 

Copy back the content but do not free the elements buffer.

FreeElements 

Free the elements buffer without copying back the possible changes.


Function Documentation

void jni::FatalError ( const char *  message,
  ... 
)

Terminates current program with a message.

If JNIEnv is available to the current thread, this function calls JNIEnv::FatalError(), otherwise it logs message in a platform-specific way and calls abort().

LObject jni::FindClass ( const char *  name)

Finds class by name.

Name is a fully-qualified class name, i.e. java/lang/Class and not java.lang.Class. See JNI reference for details.
Function may return empty (NULL) object or throw Java exception.

JNIEnv* jni::GetEnv ( )

Returns JNIEnv* for the current thread.

Performs JavaVM::AttachCurrentThread().

void jni::Initialize ( JavaVM *  vm)

Initializes jni; must be called before any other jni function.

Not thread safe, must be called on startup (in JNI_OnLoad()).

Can be called multiple times, only first invocation will have an effect.

Examples:
NativeSound.cpp.
void jni::Initialize ( JNIEnv *  env)

Version of Initialize(JavaVM*) that takes JNIEnv*.

Handy when you need to initialize jni from ordinary JNI function (not from JNI_OnLoad()).

Not thread safe.

void jni::Throw ( const AbstractObject &  throwable)

Raises Java exception.

This function instructs Java VM that Java exception throwable should be thrown once control returns to the VM.

void jni::TranslateCppException ( )

Converts current C++ exception to the Java exception and raises it using jni::Throw().

This function should be used as follows:

 try {
   std::vector<int> vec(1);
   vec.at(10)=0; // throws std::out_of_range
 }
 catch (...) {
   jni::TranslateCppException();
   // java.lang.RuntimeException is raised.
 }

Translation algorithm:

  • If const jni::AbstractObject& was thrown, it is raised.
  • If const std::basic_exception& was thrown, function raises java.lang.RuntimeException with exception's message.
  • All other exception types are translated to java.lang.RuntimeException with the message of 'Unknown C++ exception'.

This function is used to translate exceptions occurred during invocation of callbacks specified in JB_DEFINE_LIVE_CLASS().

void jni::TranslateJavaException ( )

Converts currently pending Java exception to C++ exception.

If no Java exception is pending this function does nothing.

If Java exception is pending this function wraps it in private object derived from jni::AbstractObject, clears pending exception status and throws exception object by value. Use java::Cast() to cast exception object to concrete type. You can safely cast to java::Throwable class.

You should catch Java exception by const reference to jni::AbstractObject:

  try {
    java::PIntArray array=new java::IntArray(1);
    array->SetAt(10,0); // throws IndexOutOfBoundsException
  }
  catch (const jni::AbstractObject& e) {
    java::PThrowable thr=java::Cast<java::Throwable>(e);
    java::PString message=thr->GetMessage();
    printf("Exception's type: %s, message: %s\n",
      thr->GetClass()->GetName()->GetUTF(),
      message?message->GetUTF():NULL);
  }

See also jni::TranslateCppException().


Variable Documentation

const bool jni::JBooleanIsBool

Indicates whether an array of jboolean values can be cast to an array of C++ bool values.

Evaluates to

 sizeof(jboolean)==sizeof(bool) && 
   JNI_TRUE==true && JNI_FALSE==false

Bool array functions (e.g jni::GetBoolArrayElements()) use this value to decide whether to cast or convert.

Pass this object instead of NULL.

If NULL is defined as "0" on your platform, passing NULL to vararg functions will not cause a compiler error. However, NULL will be treated as int and will likely cause a crash on systems where sizeof(int)!=sizeof(void*).