[[ LCBJava ]] Add utility to convert between JObject and Pointer

livecodeali · livecodeali · commit c07caf144f52 · 2017-06-02T12:08:46.000+01:00
For some APIs we need to extract the underlying jobject pointer
from a JObject (for passing to platform-agnostic code such as
`set my native layer`, or wrap a jobject pointer in a JObject for
passing to native Java APIs. This patch adds utility functions for
such occasions.
diff --git a/docs/lcb/notes/feature-jobject_pointers.md b/docs/lcb/notes/feature-jobject_pointers.md
@@ -0,0 +1,16 @@
+# LiveCode Builder Standard Library
+
+## Java Utilities
+
+Syntax for converting between a JObject and Pointer have been added to the 
+Java utility library.
+
+* `PointerToJObject` - converts a Pointer to a JObject
+* `PointerFromJObject` - converts a JObject to a Pointer
+
+These can be used in APIs where `Pointer` is the type of a platform-agnostic 
+parameter whose underlying type is assumed to be `jobject` when used in a 
+platform-specific implementation, for example:
+
+	-- pView is assumed to be a JObject with underlying type android.view.View
+	set my native layer to PointerFromJObject(pView) 
diff --git a/libscript/src/java.lcb b/libscript/src/java.lcb
@@ -52,7 +52,8 @@ foreign handler MCJavaDataFromJByteArray(in pByteArray as JObject, out rData as
 foreign handler MCJavaDataToJByteArray(in pData as Data, out rByteArray as JObject) returns nothing binds to "<builtin>"
 
 foreign handler MCJavaGetClassName(in pObject as JObject, out rName as String) returns nothing binds to "<builtin>"
-
+foreign handler MCJavaUnwrapJObject(in pObject as JObject, out rPointer as Pointer) returns nothing binds to "<builtin>"
+foreign handler MCJavaWrapJObject(in pPointer as Pointer, out rObj as JObject) returns nothing binds to "<builtin>"
 
 /**
 Summary:    Get Java class name of a Java object
@@ -176,4 +177,71 @@ public handler DataFromJByteArray(in pBytes as JByteArray) returns Data
 	return tData
 end handler
 
+/**
+Summary:    Convert a JObject into a Pointer
+
+Parameters:
+pObj: The JObject to convert
+
+Returns:
+The jobject Pointer wrapped by the JObject type
+
+Example:
+	handler SetNativeLayerToView(in pView as JObject)
+		variable tViewPtr as Pointer
+		put PointerFromJObject(pView) into tViewPtr
+		set my native layer to tViewPtr
+	end handler
+	 
+Description:
+Use <PointerFromJObject> to convert a variable of type JObject to one of
+type Pointer, i.e. to extract the underlying jobject pointer from a JObject
+*/
+
+public handler PointerFromJObject(in pObj as JObject) returns Pointer
+	variable tPointer as Pointer
+    unsafe
+		MCJavaUnwrapJObject(pObj, tPointer)
+    end unsafe
+	return tPointer
+end handler
+
+/**
+Summary:    Convert a Pointer into a JObject
+
+Parameters:
+pPointer: The Pointer to convert
+
+Returns:
+A JObject wrapping the jobject Pointer
+
+Example:
+	foreign handler _JNI_SetTextViewText(in pView as JObject, in pValue as JString) returns nothing binds to "java:android.widget.TextView>setText(Ljava/lang/CharSequence;)V"
+	
+	-- set the text of a view
+	unsafe handler ViewSetText(in pString as String)
+		variable tViewPtr as Pointer
+		put my native layer into tPointer
+		
+		variable tView as JObject
+		put PointerToJObject into tView
+		_JNI_SetTextViewText(tView, StringToJString(pString))
+	end handler
+	 
+Description:
+Use <PointerToJObject> to convert a variable of type Pointer to one of 
+type JObject. 
+
+> *Important:* Your application will likely crash if the underlying type
+> of the Pointer is not actually jobject.
+*/
+
+public handler PointerToJObject(in pPointer as Pointer) returns JObject
+	variable tObj as JObject
+    unsafe
+		MCJavaWrapJObject(pPointer, tObj)
+    end unsafe
+	return tObj
+end handler
+
 end module
diff --git a/libscript/src/module-java.cpp b/libscript/src/module-java.cpp
@@ -43,6 +43,7 @@ MC_DLLEXPORT MCTypeInfoRef kMCJavaCouldNotConvertJStringToStringErrorTypeInfo;
 MC_DLLEXPORT MCTypeInfoRef kMCJavaCouldNotConvertDataToJByteArrayErrorTypeInfo;
 MC_DLLEXPORT MCTypeInfoRef kMCJavaCouldNotConvertJByteArrayToDataErrorTypeInfo;
 MC_DLLEXPORT MCTypeInfoRef kMCJavaCouldNotGetObjectClassNameErrorTypeInfo;
+MC_DLLEXPORT MCTypeInfoRef kMCJavaCouldNotCreateJObjectErrorTypeInfo;
 
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
@@ -91,6 +92,17 @@ extern "C" MC_DLLEXPORT_DEF void MCJavaGetClassName(MCJavaObjectRef p_obj, MCStr
         MCJavaErrorThrow(kMCJavaCouldNotGetObjectClassNameErrorTypeInfo);
 }
 
+extern "C" MC_DLLEXPORT_DEF void MCJavaUnwrapJObject(MCJavaObjectRef p_obj, void*&r_pointer)
+{
+    r_pointer = MCJavaObjectGetObject(p_obj);
+}
+
+extern "C" MC_DLLEXPORT_DEF void MCJavaWrapJObject(void *p_pointer, MCJavaObjectRef& r_obj)
+{
+    if (!MCJavaObjectCreate(p_pointer, r_obj))
+        MCJavaErrorThrow(kMCJavaCouldNotCreateJObjectErrorTypeInfo);
+}
+
 ////////////////////////////////////////////////////////////////////////////////////////////////////
 
 bool MCJavaErrorsInitialize()
@@ -109,6 +121,9 @@ bool MCJavaErrorsInitialize()
         
     if (!MCNamedErrorTypeInfoCreate(MCNAME("com.livecode.java.FetchJavaClassNameError"), MCNAME("java"), MCSTR("Could not get Java object class name"), kMCJavaCouldNotGetObjectClassNameErrorTypeInfo))
         return false;
+
+    if (!MCNamedErrorTypeInfoCreate(MCNAME("com.livecode.java.CreateJObjectError"), MCNAME("java"), MCSTR("Could not create JObject from Pointer"), kMCJavaCouldNotCreateJObjectErrorTypeInfo))
+        return false;
     
     return true;
 }
@@ -120,6 +135,7 @@ void MCJavaErrorsFinalize()
     MCValueRelease(kMCJavaCouldNotConvertDataToJByteArrayErrorTypeInfo);
     MCValueRelease(kMCJavaCouldNotConvertJByteArrayToDataErrorTypeInfo);
     MCValueRelease(kMCJavaCouldNotGetObjectClassNameErrorTypeInfo);
+    MCValueRelease(kMCJavaCouldNotCreateJObjectErrorTypeInfo);
 }
 
 extern "C" bool com_livecode_java_Initialize(void)
