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

[jonpryor]

Fixes: #10
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(), 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 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();
}

[jonpryor]

Will remain a Draft until we create & review a corresponding dotnet/android PR for integration testing…

[jpobst]

Love it, I think this will be a useful addition for users.

[jpobst]

The existing JavaCast<T> only uses [DynamicallyAccessedMembers (Constructors)], should Interfaces be added as well?

[jonpryor]

I'll leave that to @jonathanpeppers. 😅

[jonathanpeppers]

I added enough attributes to silence the analyzer's warnings on the original JavaCast<T>().

I would recommend just putting Constructors for now, if no warnings appear.

[jpobst]

There are still cases where we throw exceptions (here and in JniRuntime.JniValueManager.cs). I assume these are corner cases where the object is in a "bad state", but I think I would lean towards never throwing an exception under any circumstance. If the object is bad and we return null, the user cannot use it anyways.

[jonpryor]

I mentally split this into two "important" bits:

1. Java type checking, and
2. Things that could never succeed, and would indicate a fundamental error.

The exceptions are for (2). For example, what if someone wanted to use this to convert a Java type to System.ICloneable:

var wat = new Java.Lang.Object().JavaAs<System.ICloneable>();

This would fail to compile right now, due to the generic constraints on JavaAs() (yay), but if someone avoided those constraints (e.g. directly hit JniEnvironment.Runtime.ValueManager.CreatePeer(), use MemberInfo.MakeGenericMethod() at runtime to create an invalid instantiation {untested; maybe that'll throw?}), then I think it would be better to always throw, because the usage is bad.

[jonpryor]

Though this check being first means I'm fibbing about "always checking for fundamental errors"; if the value were always null, for whatever reason, we'd never get around to "sanity checking" whether it's even possible. 🤔

[AmrAlSayed0]

I guess this PR fixes this issue #10 too

[jonathanpeppers]

Do we need a test that tries to cast to a random, incorrect type like System.Guid? (One that isn't even a Java thing) Would that case throw?

[jpobst]

I believe the case you are suggesting is compiler prevented by the generic constraint?

public static TResult? JavaAs<TResult> (this IJavaPeerable? self)
    where TResult : class, IJavaPeerable
{ ... }

Or perhaps I misunderstand your comment.

[jonathanpeppers]

Otherwise, this looks good to me. I just wondered about the one case.