/Volumes/E/Github/itoa-jnipp/include/JNIpp/JavaBinding.h File Reference

Provides macros for implementing live and wrapper classes. More...

Namespaces
namespace	jb
	Contains implementation details of JB_ macros; see JavaBinding.h for the list.
Defines
#define	JB_CURRENT_CLASS
	Sets current class; needs to be defined before using any other JB_ macros.
#define	JB_WRAPPER_CLASS(Type)
	Declares Type to be Java wrapper class.
#define	JB_LIVE_CLASS(Type)
	Declares Type to be Java live class.
#define	JB_DEFINE_ACCESSOR(JavaName, FieldsSpec, MethodsSpec)
	Defines Java bindings for the current accessor class.
#define	JB_DEFINE_WRAPPER_CLASS(JavaName, Fields, Methods)
	Defines Java bindings for the current wrapper class.
#define	JB_NATIVE_INSTANCE_NAME
	Name of the int variable in Java class that holds instance pointer; default is nativeInstance.
#define	JB_DEFINE_LIVE_CLASS(JavaName, FieldsSpec, MethodsSpec, CallbacksSpec)
	Defines Java bindings for the current live class.
#define	JB_INIT_CLASS()
	Initializes data structures defined by JB_DEFINE_ macros.
#define	JB_GET_CLASS()
	Returns java::PClass for the current class.
#define	JB_GET_METHOD_ID(MethodTag)
	Returns jmethodID for the tag.
#define	JB_GET_FIELD_ID(FieldTag)
	Returns fieldID for the tag.
#define	JB_NEW(ConstructorTag,...)
	Allocates new instance of Java class and calls constructor method identified by ConstructorTag.
#define	JB_CALL(WhichMethod, object, MethodTag,...)
	Calls method identified by MethodTag on object.
#define	JB_CALL_THIS(WhichMethod, MethodTag,...)
	Calls method identified by MethodTag on the current object; use in member functions.
#define	JB_NVCALL(WhichMethod, object, MethodTag,...)
	Nonvirtually calls method identified by MethodTag on object.
#define	JB_NVCALL_THIS(WhichMethod, MethodTag,...)
	Nonvirtually calls method identified by MethodTag on the current object; use in member functions.
#define	JB_CALL_STATIC(WhichMethod, MethodTag,...)
	Calls static method identified by MethodTag.
#define	JB_GET(WhichField, object, FieldTag)
	Retrieves value of the field identified by FieldTag from object.
#define	JB_GET_THIS(WhichField, FieldTag)
	Retrieves value of the field identified by FieldTag from the current object; use in member functions.
#define	JB_SET(WhichField, object, FieldTag, value)
	Sets value to the field identified by FieldTag on object.
#define	JB_SET_THIS(WhichField, FieldTag, value)
	Sets value to the field identified by FieldTag on the current object; use in member functions.
#define	JB_GET_STATIC(WhichField, FieldTag)
	Retrieves value from the static field identified by FieldTag.
#define	JB_SET_STATIC(WhichField, FieldTag, value)
	Sets value to the static field identified by FieldTag.

---

Detailed Description

Provides macros for implementing live and wrapper classes.

---

Define Documentation

#define JB_CALL	(		WhichMethod,
			object,
			MethodTag,
			...
	)

Calls method identified by MethodTag on object.

WhichMethod specifies return type of the Java method identified by MethodTag. For example, if MethodTag refers to method returning int WhichMethod must be IntMethod.

Possible values of WhichMethod:

• VoidMethod, for methods that return nothing.
• BooleanMethod, for Java methods returning boolean.
• BoolMethod, for Java methods returning boolean; return value is converted to bool.
• ByteMethod, for Java methods returning byte.
• ShortMethod, for Java methods returning short.
• CharMethod, for Java methods returning char.
• IntMethod, for Java methods returning int.
• LongMethod, for Java methods returning long.
• FloatMethod, for Java methods returning float.
• DoubleMethod, for Java methods returning double.
• ObjectMethod, for Java methods returning objects or arrays.

When calling ObjectMethod use java::ObjectPointer::Wrap() to convert return value to an instance of concrete class:

 typedef java::ObjectPointer<MyClass> PMyClass;
 PMyClass my=PMyClass::Wrap(JB_CALL(ObjectMethod,object,MethodTag));
 my->DoSomething();

This macro expands to jni::Call##WhichMethod().

#define JB_CALL_STATIC	(		WhichMethod,
			MethodTag,
			...
	)

Calls static method identified by MethodTag.

See JB_CALL() for WhichMethod values.

This macro expands to jni::CallStatic##WhichMethod().

Examples:

EmailValidator.cpp, and LiveThread.cpp.

#define JB_CALL_THIS	(		WhichMethod,
			MethodTag,
			...
	)

Calls method identified by MethodTag on the current object; use in member functions.

See also: JB_CALL().

Examples:

EmailValidator.cpp, and LiveThread.cpp.

#define JB_CURRENT_CLASS

Sets current class; needs to be defined before using any other JB_ macros.

When implementing wrapper or live class JB_CURRENT_CLASS should match class name. When used with JB_DEFINE_ACCESSOR() it can be arbitrary (but unique) name.

JB_CURRENT_CLASS must be undefined at the end of implementation.

 #define JB_CURRENT_CLASS MyWrapperClass

 JB_DEFINE_WRAPPER_CLASS(...)

 Implementation of MyWrapperClass methods using
  JB_ macros like JB_SET() or JB_NEW().

 #undef JB_CURRENT_CLASS 

#define JB_DEFINE_ACCESSOR	(		JavaName,
			FieldsSpec,
			MethodsSpec
	)

Defines Java bindings for the current accessor class.

This macro is equivalent to JB_DEFINE_WRAPPER_CLASS() except that it doesn't implement any class methods.

Accessor classes are useful when you want to provide interface to the Java class as a set of global static functions (example: GC() global function that calls System.gc()).

#define JB_DEFINE_LIVE_CLASS	(		JavaName,
			FieldsSpec,
			MethodsSpec,
			CallbacksSpec
	)

Defines Java bindings for the current live class.

This macro implements member functions declared by JB_LIVE_CLASS() and also defines fields, methods and callbacks that will be used to implement current live class.

See JB_DEFINE_WRAPPER_CLASS() for description of JavaName, FieldsSpec and MethodsSpec.

Callback is a member function of a live class which will be called when corresponding Java method is called. Java methods which are bound to callbacks must be marked with 'native' keywords.

CallbacksSpec is either

• Single identifier NoCallbacks, when no callbacks are specified, or
• Identifier Callbacks followed by a number of callback specs of form (Binding, Name, Descriptor), where
  • Binding specifies function that will be bound to the Java method (see below).
  • Name is a name of Java method. No indication is required for the static methods.
  • Descriptor is a Java method descriptor. See 12.3.4 "Methods Descriptors" in JNI specification.

Binding has the form Method(MethodName) where MethodName identifies method in the current live class.

Facts about callback methods:

• Callback methods are subject to the restrictions specified by jni::VarArgs.
• Currently callback methods can't be const (will be fixed in next release).
• C++ exceptions thrown from callback methods are translated to the Java exceptions by jni::TranslateCppException().
• Callback methods can be static. In this case method must include extra argument of object type. When static callback method is bound to non-static Java method that extra argument is a Java object which called the callback, otherwise it is Java class callback is bound to.

 *** Java ***
 public native String[] parse(String input);
 private static native Object loadObject(int cookie);

 *** C++ ***
 java::PStringArray Parse(java::PString);
 // Note extra java::PClass argument.
 static java::PObject LoadObject(java::PClass,int cookie);

 JB_DEFINE_LIVE_CLASS(
   ...
   ,
   Callbacks
   (Method(Parse),"parse","(Ljava/lang/String;)[Ljava/lang/String;")
   (Method(LoadObject),"loadObject","(I)Ljava/lang/Object;")
 )

Examples:

LiveThread.cpp, and NativeSound.cpp.

#define JB_DEFINE_WRAPPER_CLASS	(		JavaName,
			Fields,
			Methods
	)

Defines Java bindings for the current wrapper class.

This macro implements member functions declared by JB_WRAPPER_CLASS() and also defines fields and methods that will be used to implement current wrapper class.

JavaName is a fully-qualified name of Java class, see 12.3.2 "Class Descriptors" in JNI specification.

FieldsSpec is either

• Single identifier NoFields, when no fields are specified, or
• Identifier Fields followed by a number of field specs of form (Tag, Name, Descriptor).

MethodSpec is either

• Single identifier NoMethods, when no methods are specified, or
• Identifier Methods followed by a number of method specs of form (Tag, Name, Descriptor).

Where

• Tag is an arbitrary tag identifying field or method. It is used when accessing fields (JB_GET()/JB_SET()) or calling methods (JB_CALL() and the like).
• Name is field or method name as defined in Java class. It doesn'tinclude any type or signature information. To indicate a static field or method start name with a plus sign (e.g. "+myStaticField", "+myStaticMethod").
• Descriptor is field/method descriptor. See 12.3.3 "Field Descriptors" or 12.3.4 "Method Descriptors" in JNI specification.

 *** Java ***
 public double factor;
 private static Object[] cache;

 public double scale(int value) {...}
 public static boolean isCached(Object value) {...}

 *** C++ ***
 JB_DEFINE_WRAPPER_CLASS(
   "com/my/SomeClass"
   ,
   Fields
   (FactorTag,"factor","D")
   (CacheTag,"+cache","[Ljava/lang/Object;")
   ,
   Methods
   (ScaleTag,"scale","(I)D")
   (IsCachedTag,"+isCached","(Ljava/lang/Object;)Z")
 )

 JB_SET_THIS(DoubleField,FactorTag,factor);
 java::PObjectArray cache=java::PObjectArray::Wrap(
   JB_GET_STATIC(ObjectMethod,CacheTag));

 double scaled=JB_CALL_THIS(DoubleMethod,ScaleTag,value);
 bool isCached=JB_CALL_STATIC(BoolMethod,IsCachedTag,object);

Examples:

EmailValidator.cpp, LiveThread.cpp, and NativeSound.cpp.

#define JB_GET	(		WhichField,
			object,
			FieldTag
	)

Retrieves value of the field identified by FieldTag from object.

WhichField specifies type of the Java field identified by FieldTag. For example, if FieldTag refers to field of type long WhichField must be LongField.

Possible values of WhichField:

• BooleanField, for accessing boolean fields.
• BoolField, for accessing boolean fields; value is converted to/from bool.
• ByteField, for accessing byte fields.
• ShortField, for accessing short fields.
• CharField, for accessing char fields.
• IntField, for accessing int fields.
• LongField, for accessing long fields.
• FloatField, for accessing float fields.
• DoubleField, for accessing double fields.
• ObjectField, for accessing object or array fields.

When retrieving ObjectField use java::ObjectPointer::Wrap() to convert return value to an instance of concrete class:

 typedef java::ObjectPointer<MyClass> PMyClass;
 PMyClass my=PMyClass::Wrap(JB_GET(ObjectMethod,object,FieldTag));
 my->DoSomething();

This macro expands to jni::Get##WhichField(object).

#define JB_GET_STATIC	(		WhichField,
			FieldTag
	)

Retrieves value from the static field identified by FieldTag.

See JB_GET() for WhichField values.

This macro expands to jni::GetStatic##WhichField(object).

#define JB_GET_THIS	(		WhichField,
			FieldTag
	)

Retrieves value of the field identified by FieldTag from the current object; use in member functions.

See also: JB_GET().

Examples:

NativeSound.cpp.

#define JB_INIT_CLASS

(

)

Initializes data structures defined by JB_DEFINE_ macros.

Initialization consists of getting Java class by specified fully qualified name, getting ids for all fields and methods and binding callbacks. Any error during initialization treated as fatal error and jni::FatalError() is called.

Generally you don't need to call this method, it is implicitly called when needed. The only exception is when you need to bind callbacks to the Java class.

Examples:

NativeSound.cpp.

#define JB_LIVE_CLASS

(

Type

)

Declares Type to be Java live class.

Macro declares the following:

• const static bool IsLiveType=true;
• static java::PClass GetTypeClass();
• static jfieldID GetInstanceFieldID();
• Couple of internal implementation details.

Macro changes access to private.

 class MyLiveClass: public java::Object {
   JB_LIVE_CLASS(MyLiveClass);
 public:
   ...
 };

See also: JB_DEFINE_LIVE_CLASS().

Examples:

LiveThread.h, and NativeSound.h.

#define JB_NEW	(		ConstructorTag,
			...
	)

Allocates new instance of Java class and calls constructor method identified by ConstructorTag.

Constructors are ordinary methods having name of "<init>" and void (V) return type.

Examples:

LiveThread.cpp, and NativeSound.cpp.

#define JB_NVCALL	(		WhichMethod,
			object,
			MethodTag,
			...
	)

Nonvirtually calls method identified by MethodTag on object.

See JB_CALL() for WhichMethod values.

This macro expands to jni::CallNonvirtual##WhichMethod().

#define JB_NVCALL_THIS	(		WhichMethod,
			MethodTag,
			...
	)

Nonvirtually calls method identified by MethodTag on the current object; use in member functions.

See also JB_NVCALL().

#define JB_SET	(		WhichField,
			object,
			FieldTag,
			value
	)

Sets value to the field identified by FieldTag on object.

See JB_GET() for WhichField values.

This macro expands to jni::Set##WhichField(object,value).

#define JB_SET_STATIC	(		WhichField,
			FieldTag,
			value
	)

Sets value to the static field identified by FieldTag.

See JB_GET() for WhichField values.

This macro expands to jni::SetStatic##WhichField(object,value).

#define JB_SET_THIS	(		WhichField,
			FieldTag,
			value
	)

Sets value to the field identified by FieldTag on the current object; use in member functions.

See JB_GET() for WhichField values.

See also: JB_SET().

#define JB_WRAPPER_CLASS

(

Type

)

Declares Type to be Java wrapper class.

Macro declares the following:

• const static bool IsLiveType=false;
• static java::PClass GetTypeClass();

Macro changes access to private.

 class MyWrapper: public java::Object {
   JB_WRAPPER_CLASS(MyWrapper);
 public:
   ...
 };

See also: JB_DEFINE_WRAPPER_CLASS().

Examples:

EmailValidator.h, LiveThread.h, and NativeSound.h.