[Java.Interop] Add .JavaAs() extension method

Fixes: dotnet/android#9038

Context: 1adb796

Imagine the following Java type hierarchy:

	// Java
	public abstract class Drawable {
	    public static Drawable createFromStream(IntputStream is, String srcName) {…}
	    // …
	}
	public interface Animatable {
	    public void start();
	    // …
	}
	/* package */ class SomeAnimatableDrawable extends Drawable implements Animatable {
	    // …
	}

Further imagine that a call to `Drawable.createFromStream()` returns
an instance of `SomeAnimatableDrawable`.

What does the *binding* `Drawable.CreateFromStream()` return?

	// C#
	var drawable = Drawable.CreateFromStream(input, name);

The binding `Drawable.CreateFromStream()` look at the runtime type
of the value returned, see that it's of type `SomeAnimatableDrawable`,
and look for an existing binding of that type.  If no such binding is
found -- which will be the case here, as `SomeAnimatableDrawable` is
package-private -- then we check the value's base class, ad infinitum,
until we hit a type that we *do* have a binding for (or fail
catastrophically when we can't find a binding for `java.lang.Object`).
See also [`TypeManager.CreateInstance()`][0], which is similar to the
code within `JniRuntime.JniValueManager.GetPeerConstructor()`.

Any interfaces implemented by Java value are not consulted.  Only
the base class hiearchy.

For the sake of discussion, assume that `drawable` will be an
instance of `DrawableInvoker` (e.g. 1adb796), akin to:

	internal class DrawableInvoker : Drawable {
	    // …
	}

Further imagine that we want to invoke `Animatable` methods on
`drawable`.  How do we do this?

This is where the [`.JavaCast<TResult>()` extension method][1] comes
in: we can use `.JavaCast<TResult>()` to perform a Java-side type
check the type cast, which returns a value which can be used to
invoke methods on the specified type:

	var animatable = drawable.JavaCast<IAnimatable>();
	animatable.Start();

The problem with `.JavaCast<TResult>()` is that it always throws on
failure:

	var someOtherIface = drawable.JavaCast<ISomethingElse>();
	// throws some exception…

@mattleibow requests an "exception-free JavaCast overload" so that he
can *easily* use type-specific functionality *optionally*.

Add the following extension methods on `IJavaPeerable`:

	static class JavaPeerableExtensions {
	    public static TResult? JavaAs<TResult>(
	            this IJavaPeerable self);
	    public static bool TryJavaCast<TResult>(
	            this IJavaPeerable self,
	            out TResult? result);
	}

The `.JavaAs<TResult>()` extension method mirrors the C# `as`
operator, returning `null` if the type coercion would fail.
This makes it useful for one-off invocations:

	drawable.JavaAs<IAnimatable>()?.Start();

The `.TryJavaCast<TResult>()` extension method follows the
`TryParse()` pattern, returning true if the type coercion succeeds
and the output `result` parameter is non-null, and false otherwise.
This allows "nicely scoping" things within an `if`:

	if (drawable.TryJavaCast<IAnimatable>(out var animatable)) {
	    animatable.Start();
	    // …
	    animatable.Stop();
	}

[0]: https://github.com/dotnet/android/blob/06bb1dc6a292ef5618a3bb6ecca3ca869253ff2e/src/Mono.Android/Java.Interop/TypeManager.cs#L276-L291
[1]: https://github.com/dotnet/android/blob/06bb1dc6a292ef5618a3bb6ecca3ca869253ff2e/src/Mono.Android/Android.Runtime/Extensions.cs#L9-L17

Author: jonpryor

src/Java.Interop/Java.Interop/JavaPeerableExtensions.cs

@@ -1,6 +1,7 @@
 #nullable enable
 
 using System;
+using System.Diagnostics.CodeAnalysis;
 
 namespace Java.Interop {
 
@@ -11,5 +12,40 @@ public static class JavaPeerableExtensions {
 			JniPeerMembers.AssertSelf (self);
 			return JniEnvironment.Types.GetJniTypeNameFromInstance (self.PeerReference);
 		}
+
+		public static bool TryJavaCast<
+				[DynamicallyAccessedMembers (JavaObject.ConstructorsAndInterfaces)]
+				TResult
+		> (this IJavaPeerable? self, [NotNullWhen (true)] out TResult? result)
+			where TResult : class, IJavaPeerable
+		{
+			result = JavaAs<TResult> (self);
+			return result != null;
+		}
+
+		public static TResult? JavaAs<
+				[DynamicallyAccessedMembers (JavaObject.ConstructorsAndInterfaces)]
+				TResult
+		> (this IJavaPeerable? self)
+			where TResult : class, IJavaPeerable
+		{
+			if (self == null) {
+				return null;
+			}
+
+			if (self is TResult result) {
+				return result;
+			}
+
+			if (!self.PeerReference.IsValid) {
+				throw new ObjectDisposedException (self.GetType ().FullName);
+			}
+
+			var r = self.PeerReference;
+			return JniEnvironment.Runtime.ValueManager.CreatePeer (
+					ref r, JniObjectReferenceOptions.Copy,
+					targetType: typeof (TResult))
+				as TResult;
+		}
 	}
 }

src/Java.Interop/Java.Interop/JniRuntime.JniValueManager.cs

@@ -276,16 +276,45 @@ static Type GetPeerType ([DynamicallyAccessedMembers (Constructors)] Type type)
 				if (disposed)
 					throw new ObjectDisposedException (GetType ().Name);
 
+				if (!reference.IsValid) {
+					return null;
+				}
+
 				targetType  = targetType ?? typeof (JavaObject);
 				targetType  = GetPeerType (targetType);
 
 				if (!typeof (IJavaPeerable).IsAssignableFrom (targetType))
 					throw new ArgumentException ($"targetType `{targetType.AssemblyQualifiedName}` must implement IJavaPeerable!", nameof (targetType));
 
-				var ctor = GetPeerConstructor (reference, targetType);
-				if (ctor == null)
+				var targetSig  = Runtime.TypeManager.GetTypeSignature (targetType);
+				if (!targetSig.IsValid || targetSig.SimpleReference == null) {
+					throw new ArgumentException ($"Could not determine Java type corresponding to `{targetType.AssemblyQualifiedName}`.", nameof (targetType));
+				}
+
+				var refClass    = JniEnvironment.Types.GetObjectClass (reference);
+				JniObjectReference targetClass;
+				try {
+					targetClass = JniEnvironment.Types.FindClass (targetSig.SimpleReference);
+				} catch (Exception e) {
+					JniObjectReference.Dispose (ref refClass);
+					throw new ArgumentException ($"Could not find Java class `{targetSig.SimpleReference}`.",
+							nameof (targetType),
+							e);
+				}
+
+				if (!JniEnvironment.Types.IsAssignableFrom (refClass, targetClass)) {
+					JniObjectReference.Dispose (ref refClass);
+					JniObjectReference.Dispose (ref targetClass);
+					return null;
+				}
+
+				JniObjectReference.Dispose (ref targetClass);
+
+				var ctor = GetPeerConstructor (ref refClass, targetType);
+				if (ctor == null) {
 					throw new NotSupportedException (string.Format ("Could not find an appropriate constructable wrapper type for Java type '{0}', targetType='{1}'.",
 							JniEnvironment.Types.GetJniTypeNameFromInstance (reference), targetType));
+				}
 
 				var acts = new object[] {
 					reference,
@@ -303,11 +332,10 @@ static Type GetPeerType ([DynamicallyAccessedMembers (Constructors)] Type type)
 			static  readonly    Type    ByRefJniObjectReference = typeof (JniObjectReference).MakeByRefType ();
 
 			ConstructorInfo? GetPeerConstructor (
-					JniObjectReference instance,
+					ref JniObjectReference klass,
 					[DynamicallyAccessedMembers (Constructors)]
 					Type fallbackType)
 			{
-				var klass       = JniEnvironment.Types.GetObjectClass (instance);
 				var jniTypeName = JniEnvironment.Types.GetJniTypeNameFromClass (klass);
 
 				Type? type = null;

src/Java.Interop/PublicAPI.Unshipped.txt

@@ -1 +1,3 @@
 #nullable enable
+static Java.Interop.JavaPeerableExtensions.TryJavaCast<TResult>(this Java.Interop.IJavaPeerable? self, out TResult? result) -> bool
+static Java.Interop.JavaPeerableExtensions.JavaAs<TResult>(this Java.Interop.IJavaPeerable? self) -> TResult?

tests/Java.Interop-Tests/Java.Interop-Tests.csproj

@@ -41,6 +41,8 @@
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\CallVirtualFromConstructorBase.java" />
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\CallVirtualFromConstructorDerived.java" />
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\GetThis.java" />
+    <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\JavaInterface.java" />
+    <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\MyJavaInterfaceImpl.java" />
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\ObjectHelper.java" />
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\RenameClassBase1.java" />
     <JavaInteropTestJar Include="$(MSBuildThisFileDirectory)java\net\dot\jni\test\RenameClassBase2.java" />

tests/Java.Interop-Tests/Java.Interop/JavaPeerableExtensionsTests.cs

@@ -0,0 +1,106 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+using Java.Interop;
+
+using NUnit.Framework;
+
+namespace Java.InteropTests;
+
+[TestFixture]
+public class JavaPeerableExtensionsTests {
+
+	[Test]
+	public void JavaAs_Exceptions ()
+	{
+		using var v = new MyJavaInterfaceImpl ();
+
+		// The Java type corresponding to JavaObjectWithMissingJavaPeer doesn't exist
+		Assert.Throws<ArgumentException>(() => v.JavaAs<JavaObjectWithMissingJavaPeer>());
+
+		var r = v.PeerReference;
+		using var o = new JavaObject (ref r, JniObjectReferenceOptions.Copy);
+		// MyJavaInterfaceImpl doesn't provide an activation constructor
+		Assert.Throws<NotSupportedException>(() => o.JavaAs<MyJavaInterfaceImpl>());
+#if !__ANDROID__
+		// JavaObjectWithNoJavaPeer has no Java peer
+		Assert.Throws<ArgumentException>(() => v.JavaAs<JavaObjectWithNoJavaPeer>());
+#endif  // !__ANDROID__
+	}
+
+	[Test]
+	public void JavaAs_NullSelfReturnsNull ()
+	{
+		Assert.AreEqual (null, JavaPeerableExtensions.JavaAs<IAndroidInterface> (null));
+	}
+
+	[Test]
+	public void JavaAs_InstanceThatDoesNotImplementInterfaceReturnsNull ()
+	{
+		using var v = new MyJavaInterfaceImpl ();
+		Assert.AreEqual (null, JavaPeerableExtensions.JavaAs<IAndroidInterface> (v));
+	}
+
+	[Test]
+	public void JavaAs ()
+	{
+		using var impl  = new MyJavaInterfaceImpl ();
+		using var iface = impl.JavaAs<IJavaInterface> ();
+		Assert.IsNotNull (iface);
+		Assert.AreEqual ("Hello from Java!", iface.Value);
+	}
+}
+
+// Note: Java side implements JavaInterface, while managed binding DOES NOT.
+[JniTypeSignature (JniTypeName, GenerateJavaPeer=false)]
+class MyJavaInterfaceImpl : JavaObject {
+	internal            const       string          JniTypeName    = "net/dot/jni/test/MyJavaInterfaceImpl";
+
+	internal    static  readonly    JniPeerMembers  _members    = new JniPeerMembers (JniTypeName, typeof (MyJavaInterfaceImpl));
+
+	public override JniPeerMembers JniPeerMembers {
+		get {return _members;}
+	}
+
+	public unsafe MyJavaInterfaceImpl ()
+		: base (ref *InvalidJniObjectReference, JniObjectReferenceOptions.None)
+	{
+		const   string  id  = "()V";
+		var peer = _members.InstanceMethods.StartCreateInstance (id, GetType (), null);
+		Construct (ref peer, JniObjectReferenceOptions.CopyAndDispose);
+		_members.InstanceMethods.FinishCreateInstance (id, this, null);
+	}
+}
+
+[JniTypeSignature (JniTypeName, GenerateJavaPeer=false)]
+interface IJavaInterface : IJavaPeerable {
+	internal            const       string          JniTypeName    = "net/dot/jni/test/JavaInterface";
+
+	public string Value {
+		[JniMethodSignatureAttribute("getValue", "()Ljava/lang/String;")]
+		get;
+	}
+}
+
+internal class IJavaInterfaceInvoker : JavaObject, IJavaInterface {
+
+	internal    static  readonly    JniPeerMembers  _members    = new JniPeerMembers (IJavaInterface.JniTypeName, typeof (IJavaInterfaceInvoker));
+
+	public override JniPeerMembers JniPeerMembers {
+		get {return _members;}
+	}
+
+	public IJavaInterfaceInvoker (ref JniObjectReference reference, JniObjectReferenceOptions options)
+		: base (ref reference, options)
+	{
+	}
+
+	public unsafe string Value {
+		get {
+			const string id = "getValue.()Ljava/lang/String;";
+			var r = JniPeerMembers.InstanceMethods.InvokeVirtualObjectMethod (id, this, null);
+			return JniEnvironment.Strings.ToString (ref r, JniObjectReferenceOptions.CopyAndDispose);
+		}
+	}
+}

tests/Java.Interop-Tests/Java.Interop/JniPeerMembersTests.cs

@@ -264,13 +264,23 @@ public override unsafe int hashCode ()
 	interface IAndroidInterface : IJavaPeerable {
 		internal            const       string          JniTypeName    = "net/dot/jni/test/AndroidInterface";
 
-		private static JniPeerMembers _members = new JniPeerMembers (JniTypeName, typeof (IAndroidInterface), isInterface: true);
+		internal static JniPeerMembers _members = new JniPeerMembers (JniTypeName, typeof (IAndroidInterface), isInterface: true);
 
 		public static unsafe string getClassName ()
 		{
 			var s = _members.StaticMethods.InvokeObjectMethod ("getClassName.()Ljava/lang/String;", null);
 			return JniEnvironment.Strings.ToString (ref s, JniObjectReferenceOptions.CopyAndDispose);
 		}
 	}
+
+	internal class IAndroidInterfaceInvoker : JavaObject, IAndroidInterface {
+
+		public override JniPeerMembers JniPeerMembers => IAndroidInterface._members;
+
+		public IAndroidInterfaceInvoker (ref JniObjectReference reference, JniObjectReferenceOptions options)
+			: base (ref reference, options)
+		{
+		}
+	}
 #endif  // NET
 }

tests/Java.Interop-Tests/java/net/dot/jni/test/JavaInterface.java

@@ -0,0 +1,6 @@
+package net.dot.jni.test;
+
+public interface JavaInterface {
+
+	String getValue();
+}

tests/Java.Interop-Tests/java/net/dot/jni/test/MyJavaInterfaceImpl.java

@@ -0,0 +1,9 @@
+package net.dot.jni.test;
+
+public class MyJavaInterfaceImpl
+	implements JavaInterface
+{
+	public String getValue() {
+		return "Hello from Java!";
+	}
+}