[Java.Interop] Use ref return for elements access (#260)

While reviewing [DoNotThrowInUnexpectedLocationRule][throw] regarding
`JniArrayElements.Elements` we discussed the issue and came up with
a slight semantic API overhaul.

[throw]: https://github.com/spouliot/gendarme/wiki/Gendarme.Rules.Exceptions.DoNotThrowInUnexpectedLocationRule(2.10)

Previously, we had:

	public abstract partial class JniArrayElements : IDisposable {
	  public IntPtr Elements {get;}

	  public void CopyToJava();
	  public void Dispose();
	  public void Release(JniReleaseArrayElementsMode releaseMode);
	}

	public sealed class JniInt32ArrayElements : JniArrayElements {
	  public new unsafe int* Elements {get;}
	}

The *idea* of `JniArrayElements` was that it refers to a contiguous
blob of memory, starting at address `JniArrayElements.Elements`.
The thinking was that `JniArrayElements` would allow reading or
otherwise manipulating the memory regions without needing to know
the underlying element type.

On further discussion, this abstraction was missing something
important: the *size* of the region of memory that
`JniArrayElements.Elements` refers to.

Additionally, with the advent of [C# 7 ref returns][rr], we thought
that providing a ref-return indexer would be preferable to using a
shadowing/re-declared `Elements` property.

[rr]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/ref-returns

We also considered using `Span<T>/Memory<T>`; it is not available in
mono at this time. It should be possible to add support for them
when they are supported.

With these changes, the updated public API is:


	public abstract partial class JniArrayElements : IDisposable {
	  public IntPtr     Elements {get;}
	  public int        Size     {get;}

	  public void CopyToJava();
	  public void Dispose();
	  public void Release(JniReleaseArrayElementsMode releaseMode);
	}

	public sealed class JniInt32ArrayElements : JniArrayElements {
	  public ref int this [int index] {get;}
	}

Author: radekdoulik

gendarme-ignore.txt

@@ -688,3 +688,15 @@ M: System.String <>__AnonType1`2::ToString()
 R: Gendarme.Rules.Exceptions.DoNotThrowInUnexpectedLocationRule
 # throwing ArgumentOutOfRangeException is OK according to the documentation https://msdn.microsoft.com/library/system.collections.ilist.item(v=vs.110).aspx
 M: T Java.Interop.JavaObjectArray`1::get_Item(System.Int32)
+# we want these to check for disposed state, throwing ObjectDisposedException is better and not much different than suggested InvalidOperationException
+M: System.Boolean& Java.Interop.JniBooleanArrayElements::get_Item(System.Int32)
+M: System.SByte& Java.Interop.JniSByteArrayElements::get_Item(System.Int32)
+M: System.Char& Java.Interop.JniCharArrayElements::get_Item(System.Int32)
+M: System.Int16& Java.Interop.JniInt16ArrayElements::get_Item(System.Int32)
+M: System.Int32& Java.Interop.JniInt32ArrayElements::get_Item(System.Int32)
+M: System.Int64& Java.Interop.JniInt64ArrayElements::get_Item(System.Int32)
+M: System.Single& Java.Interop.JniSingleArrayElements::get_Item(System.Int32)
+M: System.Double& Java.Interop.JniDoubleArrayElements::get_Item(System.Int32)
+# we want to check for disposed state here
+M: System.IntPtr Java.Interop.JniArrayElements::get_Elements()
+M: System.Int32 Java.Interop.JniArrayElements::get_Size()

src/Java.Interop/Java.Interop/JavaArray.cs

@@ -295,15 +295,17 @@ void IList<T>.RemoveAt (int index)
 	public abstract class JniArrayElements : IDisposable {
 
 		IntPtr elements;
+		int size;
 
-		internal JniArrayElements (IntPtr elements)
+		internal JniArrayElements (IntPtr elements, int size)
 		{
 			if (elements == IntPtr.Zero)
 				throw new ArgumentException ("'elements' must not be IntPtr.Zero.", nameof (elements));
 			this.elements = elements;
+			this.size = size;
 		}
 
-		bool IsDisposed {
+		internal bool IsDisposed {
 			get {return elements == IntPtr.Zero;}
 		}
 
@@ -315,6 +317,14 @@ public  IntPtr  Elements {
 			}
 		}
 
+		public int Size {
+			get {
+				if (IsDisposed)
+					throw new ObjectDisposedException (GetType ().FullName);
+				return size;
+			}
+		}
+
 		protected   abstract    void    Synchronize (JniReleaseArrayElementsMode releaseMode);
 
 		public void CopyToJava ()