[Mono.Android] API-compatible CellInfo.CellIdentity

[jonpryor]

Add Documentation/workflow/mono-android-api-compatibility.md, which
describes the scenarios we need to be familiar with regarding Java and
C# API compatibility differences and how to deal with them, and update
Mono.Android.dll for API-R so that e.g.
Android.Telephony.CellInfoGsm.CellIdentity doesn't change types vs.
API-29 (the previous version).

[gugavaro]

This is a very interesting solution to solve this break. One thing that comes to my mind is if this code inside the get will ever be executed? In which condition this path would run? Would be safe to actually assert inside this get?

[jonpryor]

Yes, it can be executed. Consider:

CellInfo     cell     = new CellInfoCdma ();
CellIdentity identity = cell.CellIdentity;

CellInfoCdma does not override the CellInfo.CellIdentity property. It can't, because in order to do so it would need to change the property type, and changing the property type would be a compatibility break.

Now, a downside to this approach is that if you build your app against API-R and use the CellInfo.CellIdentity property, then run the app on e.g. an API-29 device, cell.CellIdentity will throw, because API-29 doesn't have a CellInfo.getCellIdentity() method.

What I don't know is if this behavior is consistent with Java. I assume it would be, but haven't tested. (Could someone please test this? :-)

Even if this behavior is consistent with Java, it's kinda "less than ideal", because there is a CellInfoCdma.CellIdentity property which does work on API-29, so why should this throw?

If we think that cell.CellIdentity should work on API-29, then we need an indirection:

partial class CellIdentity {
    public virtual Android.Telephony.CellIdentity CellIdentity {
        [Register (...)]
        get => _GetCellIdentityCore ();

    internal virtual Android.Telephony.CellIdentity _GetCellIdentityCore ()
    {
        const string __id = "getCellIdentity.()Landroid/telephony/CellIdentity;";
        try {
            var __rm = _members.InstanceMethods.InvokeVirtualObjectMethod (__id, this, null);
            return global::Java.Lang.Object.GetObject<Android.Telephony.CellIdentity> (__rm.Handle, JniHandleOwnership.TransferLocalRef);
        }
        catch (Java.Lang.NoSuchMethodError) {
            throw new Java.Lang.AbstractMethodError (__id);
        }
    }
}

sealed partial class CellIdentityCdma {
    public new Android.Telephony.CellIdentityCdma CellIdentity { get; }

    internal override Android.Telephony.CellIdentity _GetCellIdentityCore () => CellIdentity;
}

[jpobst]

Suggested change

	<!-- Google has added getCellIdentity and getCellSignalStrength as abstract method on the base class -->
	<!-- Google has added getCellIdentity and getCellSignalStrength as abstract method on the base class and changed return type.
	Remove these here and manually bind to preserve compatibility. -->