[Xamarin.Android.Build.Tasks] Fix @(JavaDocJar)

[jonpryor]

Fixes: #2745
Fixes: #5474

Issue #2745 noted that @(JavaDocJar) didn't work; attempting to use
it would result in an MSB3375 error:

…/Xamarin.Android.Bindings.Documentation.targets(31,5): error MSB3375: The file "obj/Debug/javadocs/glide-3.7.0-javadoc.stamp" does not exist.

This issue was subsequently hidden by 380e95e, which disabled the
_ExtractJavaDocJars target unless JDK 1.8 was being used.

There were two problems with 380e95e:

1. The _ExtractJavaDocJars target didn't need to be disabled!
   It just unzips the .jar; it does not require JDK 1.8.

2. The check for JDK 1.8 was bad, and was never True.

The bad JDK 1.8 check was later removed in a7413a2, which "fixed"
(2), but a7413a2 continued to disable _ExtractJavaDocJars,
preventing @(JavaDocJar) from being used.

The only documentation-related functionality that needed to be
disabled because of JDK 11 was @(JavaSourceJar), which got a better
fix in commits a7413a2 and 0e95ec7.

Fix the _ExtractJavaDocJars target so that it properly runs when
there are any @(JavaDocJar) items, then fix the _ExtractJavaDocJars
target so that it doesn't emit an MSB3375 error.

Note: @(JavaDocJar) is still problematic: it involves parsing
Javadoc HTML, which contains numerous "dialects" (it's why the JDK 11
commit skipped @(JavaSourceJar) support: trying to update our HTML
scrapers was "too fiddly").

Deprecate @(JavaDocJar), and remove
Xamarin.Android.Bindings.Documentation.targets from the .NET 6
installation packages. Support for $(_UseLegacyJavadocImport)=False
won't exist for .NET 6; @(JavaSourceJar) support in .NET t will
only use java-source-utils.jar (a7413a2).

Update the BindingBuildTest.cs infrastructure so that instead of
having .jar files encoded in Base64, we instead use
@(EmbeddedResource)s for the .jar files. A new UpdateResources
target will update the appropriate .jar files.

[jonathanpeppers]

Could this do something like this instead?

using var s = typeof (InlineData).Assembly.GetManifestResourceStream (name);
var buf = new byte [s.Length];
s.Read (buf, 0, buf.Length);
return buf;

I think a List<T> would potentially resize the underlying array a couple times.

[jonpryor]

That may work, but I don't know what the semantics of the stream returned by GetManifestResourceStream() is. Is it possible that for "large" files Stream.Read() won't read in everything?

[jonathanpeppers]

Maybe this one then?

using var s = typeof (InlineData).Assembly.GetManifestResourceStream (name);
using var m = new MemoryStream ();
s.CopyTo (m);
return m.ToArray ();

[radekdoulik]

We might want to pass stream length to memory stream constructor if we want to avoid resizes during the process.

[jonathanpeppers]

Should we make these properties, so they don't load the files unless the property is called? I'm thinking if I Debug a single test, it might load all these files.

It could do something like:

static byte[] javaSourceJarJavadocTestJar;
public  static  byte[]  JavaSourceJarJavadocTestJar => javaSourceJarJavadocTestJar ??= GetResourceData ("javasourcejartest-javadoc.jar");

[jonpryor]

Do we need to worry about thread safety?

[jonathanpeppers]

Yes, I guess many of the tests use NUnit's parallel feature.

[dellis1972]

Bit of a nit pick, but should this still be called InLineData? cos its not really inline its embedded ?

[radekdoulik]

This can return after reading less than data.Length bytes. https://docs.microsoft.com/en-us/dotnet/api/system.io.stream.read?view=net-5.0

[jonpryor]

@radekdoulik: lol: #5479 (comment)

[jonathanpeppers]

Ok, this file wasn't even being imported in .NET 6. So this is safe to remove.

It is only imported for "legacy" binding projects:

https://github.com/xamarin/xamarin-android/blob/a7413a2389886082c3d3422c50a7e6cc84f43d8f/src/Xamarin.Android.Build.Tasks/Xamarin.Android.Bindings.targets#L154