[Java.Base, generator] Bind all of package java.io (#968)

Context: bc5bcf4

Bind all classes and interfaces in the `java.io` package.

Binding the [`java.io.StringBufferInputStream.buffer`][0] field
exposed a `generator` bug: property setters for `String` fields would
not compile, producing:

	partial class StringBufferInputStream {
	    protected string? Buffer {
	        get { ... }
	        set {
	            const string __id = "buffer.Ljava/lang/String;";

	            var native_value = global::Java.Interop.JniEnvironment.Strings.NewString (value);
	            try {
	                _members.InstanceFields.SetValue (__id, this, native_value?.PeerReference ?? default);
	            } finally {
	                global::Java.Interop.JniObjectReference.Dispose (ref native_value);
	                GC.KeepAlive (value);
	            }
	        }
	    }
	}

Specifically, `native_value?.PeerReference` is not valid, and
unnecessary.  This was due to a bug in `BoundFieldAsProperty.cs`,
as `String` field marshaling hit the "Object" marshaling path, which
was not warranted in this case, as `String` is treated specially.

Fix this bug.

Binding [`java.io.ObjectOutputStream.PutField.write(ObjectOutput)`][1]
presented a larger binding problem: it's an `abstract` method on an
`abstract` class, *but* the `PutFieldInvoker.Write()` method was
`[Obsolete]` when `PutField.Write()` was not!

	public abstract partial class /* ObjectOutputStream. */ PutField {
	    public abstract void Write (Java.IO.IObjectOutput? p0);
	}
	internal partial class /* ObjectOutputStream. */ PutFieldInvoker : PutField {
	    [Obsolete (@"deprecated")]
	    public override void Write (Java.IO.IObjectOutput? p0) => ...
	}

This state of affairs triggers a CS0809 warning, which is an error in
Release configuration builds:

	##[error]src/Java.Base/obj/Release-net6.0/mcw/Java.IO.ObjectOutputStream.cs(311,32)
	Error CS0809: Obsolete member 'ObjectOutputStream.PutFieldInvoker.Write(IObjectOutput?)'
	  overrides non-obsolete member 'ObjectOutputStream.PutField.Write(IObjectOutput?)'

Turns Out™ that `BoundMethodAbstractDeclaration.cs` never "forwarded"
deprecated attributes?  Meaning that `abstract` methods would *never*
be `[Obsolete]`, even if their Java peer was `@deprecated`?

Update `BoundMethodAbstractDeclaration` so that if the Java method is
deprecated, the bound `abstract` method is `[Obsolete]`.  This fixes
the CS0809, as now `PutField.Write()` and `PutFieldInvoker.Write()`
are consistent with each other.

TODO: should this change be done for *all* codegen targets?

Finally, in order to make it easier to view and review the
current `Java.Base.dll` API -- without requiring that it be built
locally -- add a `_GenerateRefApi` target to `Java.Base.targets`
which uses the `Microsoft.DotNet.GenAPI` NuGet package to generate
"reference assembly source" for `Java.Base.dll`.  This is stored in
`src\Java.Base-ref.cs`.

[0]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/StringBufferInputStream.html#buffer
[1]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/ObjectOutputStream.PutField.html#write(java.io.ObjectOutput)

Author: jonpryor

Directory.Build.targets

@@ -18,6 +18,7 @@
     <PackageReference Update="Microsoft.Build.Framework"                    Version="16.11.0" />
     <PackageReference Update="Microsoft.Build.Utilities.Core"               Version="16.11.0" />
     <PackageReference Update="Microsoft.CodeAnalysis.CSharp"                Version="3.11.0" />
+    <PackageReference Update="Microsoft.DotNet.GenAPI"                      Version="7.0.0-beta.22103.1" />
     <PackageReference Update="Microsoft.NET.Test.Sdk"                       Version="16.11.0" />
     <PackageReference Update="Microsoft.NETFramework.ReferenceAssemblies"   Version="1.0.2" />
     <PackageReference Update="Mono.CSharp"                                  Version="4.0.0.143" />

src/Java.Base-ref.cs

@@ -4,6 +4,10 @@
     <GeneratorPath>$(UtilityOutputFullPath)generator.dll</GeneratorPath>
   </PropertyGroup>
 
+  <ItemGroup>
+    <PackageReference Include="Microsoft.DotNet.GenAPI" GeneratePathProperty="true" IncludeAssets="none" />
+  </ItemGroup>
+
   <Target Name="_GetJavaBaseJmodPath">
     <PropertyGroup Condition=" '$(Java11SdkDirectory)' != '' ">
       <_JavaBaseJmod>$(Java11SdkDirectory)/jmods/java.base.jmod</_JavaBaseJmod>
@@ -75,4 +79,17 @@
     </PropertyGroup>
   </Target>
 
+  <Target Name="_GenerateRefApi"
+      Condition=" '$(PkgMicrosoft_DotNet_GenAPI)' != '' And '$(TargetPath)' != '' "
+      AfterTargets="Build"
+      Inputs="$(TargetPath)"
+      Outputs="..\Java.Base-ref.cs">
+    <PropertyGroup>
+      <_GenApi>$(PkgMicrosoft_DotNet_GenAPI)/tools/netcoreapp3.1/Microsoft.DotNet.GenAPI.dll</_GenApi>
+      <_Output>-o "../Java.Base-ref.cs"</_Output>
+      <_Libpath>--lib-path "$(OutputPath.TrimEnd('\'))"</_Libpath>
+    </PropertyGroup>
+    <Exec Command="$(DotnetToolPath) $(_GenApi) &quot;$(TargetPath)&quot; $(_Libpath) $(_Output)" />
+  </Target>
+
 </Project>

src/Java.Base/Java.Base.targets

@@ -0,0 +1,13 @@
+using System;
+using System.Collections.Generic;
+using Java.Interop;
+
+namespace Java.IO {
+
+	public partial class PrintStream : Java.Lang.IAppendable {
+
+		Java.Lang.IAppendable? Java.Lang.IAppendable.Append (char p0) => Append (p0);
+		Java.Lang.IAppendable? Java.Lang.IAppendable.Append (Java.Lang.ICharSequence? p0) => Append (p0);
+		Java.Lang.IAppendable? Java.Lang.IAppendable.Append (Java.Lang.ICharSequence? p0, int p1, int p2) => Append (p0, p1, p2);
+	}
+}

src/Java.Base/Java.IO/PrintStream.cs

@@ -0,0 +1,13 @@
+using System;
+using System.Collections.Generic;
+using Java.Interop;
+
+namespace Java.IO {
+
+	public partial class Writer : Java.Lang.IAppendable {
+
+		Java.Lang.IAppendable? Java.Lang.IAppendable.Append (char p0) => Append (p0);
+		Java.Lang.IAppendable? Java.Lang.IAppendable.Append (Java.Lang.ICharSequence? p0) => Append (p0);
+		Java.Lang.IAppendable? Java.Lang.IAppendable.Append (Java.Lang.ICharSequence? p0, int p1, int p2) => Append (p0, p1, p2);
+	}
+}

src/Java.Base/Java.IO/Writer.cs

@@ -1,6 +1,8 @@
 <metadata>
   <!-- For now, just bind java.lang.* -->
-  <remove-node path="//api/package[not(starts-with(@name, 'java.lang'))]" />
+  <remove-node path="//api/package[not(starts-with(@name, 'java.lang')
+      or starts-with(@name, 'java.io')
+      )]" />
 
   <!-- Type / Namespace conflicts -->
   <ns-replace source="java.lang.module" replacement="Java.Lang.Modules" />

src/Java.Base/Transforms/Metadata.xml

@@ -152,7 +152,12 @@ protected override void WriteSetterBody (CodeWriter writer)
 			writer.Write ($"\t_members.{indirect}.SetValue (__id{(field.IsStatic ? "" : ", this")}, ");
 
 			if (opt.CodeGenerationTarget == CodeGenerationTarget.JavaInterop1) {
-				writer.WriteLine ($"{(invokeType != "Object" ? arg : $"{arg}?.PeerReference ?? default")});");
+				if (invokeType != "Object" || have_prep) {
+					writer.Write (arg);
+				} else {
+					writer.Write ($"{arg}?.PeerReference ?? default");
+				}
+				writer.WriteLine (");");
 			} else {
 				writer.WriteLine ($"{(invokeType != "Object" ? arg : "new JniObjectReference (" + arg + ")")});");
 			}

tools/generator/SourceWriters/BoundFieldAsProperty.cs

@@ -52,6 +52,11 @@ public BoundMethodAbstractDeclaration (GenBase gen, Method method, CodeGeneratio
 			if (method.DeclaringType.IsGeneratable)
 				Comments.Add ($"// Metadata.xml XPath method reference: path=\"{method.GetMetadataXPathReference (method.DeclaringType)}\"");
 
+			// TODO: shouldn't `[Obsolete]` be added for *all* CodeGenerationTargets?
+			if (opt.CodeGenerationTarget == CodeGenerationTarget.JavaInterop1 && method.Deprecated.HasValue ()) {
+				Attributes.Add (new ObsoleteAttr (method.Deprecated.Replace ("\"", "\"\"")));
+			}
+
 			SourceWriterExtensions.AddSupportedOSPlatform (Attributes, method, opt);
 
 			if (opt.CodeGenerationTarget != CodeGenerationTarget.JavaInterop1) {