[Xamarin.Android.Build.Tasks] Add Support for AndroidJavaSource to Bindings

[dellis1972]

It would be nice to be able to introduce custom Java code and API's to a
binding project. This would allow developers to simplify an API and
still expose that to the C# Developer.

Using the existing AndroidJavaSource ItemGroup we can do exactly that.
This ItemGroup now supports the Bind metadata which will build and
bind the java code prior to the main C# compiled running. Historically
AndroidJavaSource was only available on Application Projects. However
this ItemGroup can now be used in any project type. The Bind metadata
is true by default and will cause the Java code to be compiled into
a .jar file before the C# compiler is run. It will then be bound using
the Java.Interop Java->C# binding system. The final C# apis will be
generated an included in the final C# compilation.

There are some restrictions on the Java code. You can only use Java types
or types which are defined in .jar or .aar files you reference for that
project via AndroidLibrary or EmbeddedJar.
It is advised that you DO NOT export types which include Java Generics
via this mechanism. Like normal bindings, Java Generics cause significant
problems. Try to stuck to normal types if you can.

[dellis1972]

I need to make changes to this anyway to make sure the new targets do not run as part of a DTB.

[jonpryor]

I can't easily answer this from reading the PR, but one thing we should try to ensure is that when %(AndroidJavaSource.Bind)=True, we also treat this item group "As If" the files were also part of a @(JavaSourceJar), so that java-source-utils extracts parameter names from the source code.

A "unit test check" for this would be to check that the C# binding for src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/Resources/JavaSourceTestExtension.java uses the same parameter names as the Java source:

public string GreetWithQuestion (string name, Java.Util.Date date, string question) 

This may be "easiest done" by copying all %(AndroidJavaSource.Bind)=True files into a new -source.jar file:

<PropertyGroup>
  <_AndroidIntermediateBindingClassesSourceJar>$(IntermediateOutputPath)binding\bin\$(MSBuildProjectName)-source.jar</_AndroidIntermediateBindingClassesSourceJar>
</PropertyGroup>

Then adding $(_AndroidIntermediateBindingClassesSourceJar) to @(JavaSourceJar).

$(_AndroidIntermediateBindingClassesZip) and $(_AndroidIntermediateBindingClassesSourceJar) should also be "project outputs", i.e. "copied into $(OutputPath), so that dotnet pack/etc. will copy them into NuGet packages. @(EmbeddedResource) Is Bad™.

[jonpryor]

We had a call today, and made the following decisions:

• %(AndroidJavaSource.Bind) support will be a .NET 6+ only feature. It won't exist in Legacy.

• %(AndroidJavaSource.Bind) will default to True. This will be a potential breaking change; it changes semantics, causing Java code to be compiled earlier than it currently is, but it also might not actually break anybody, as we think it'll only cause compilation errors if the @(AndroidJavaSource) references Java Callable Wrapper types. Fixing the break will be easy: just set %(Bind)=False.

  Also, @(AndroidJavaSource) isn't widely used, at least not on GitHub: https://github.com/search?q=androidjavasource+extension%3Acsproj&type=Code&ref=advsearch&l=&l=

• For d16-11, we'll consider adding a check for @(AndroidJavaSource) use and issue a warning that the semantics will be changing for .NET 6.

[jonathanpeppers]

The comments I had at this point are really minor. 👍

[jonpryor]

Should this also have And Exists('$(_JavaSdkDirectory)bin')? Or will we error out earlier if $(_JavaSdkDirectory) doesn't exist?

[jonpryor]

…and shouldn't we start using <PropertyGroup/> instead of <CreateProperty/> here?

[dellis1972]

I did this to that it matches what was already there. I can rework this to use PropertyGroup. Or perhaps we get this in, and then do a PR to remove ALL CreateProperty references?

[jonpryor]

Commit message?

[Xamarin.Android.Build.Tasks] Add %(AndroidJavaSource.Bind) (#5926)

Update the `@(AndroidJavaSource)` Build action:

 1. In .NET 7, all `**\*.java` files are automatically added to the
    `@(AndroidJavaSource)` Build action.

 2. Add `%(AndroidJavaSource.Bind)` item metadata, a boolean value
    (default is True) which controls whether or not the file is
    compiled and bound *prior* to the C# build.

The combination of these means that custom Java code can be added to
any .NET Android project, and a binding of that Java code will be
usable by the C# code.  Both Java code and bindings will be included
in App builds of referencing apps.

There are some restrictions on the Java code.  You can only use Java
types or types which are defined in `.jar` or `.aar` files referenced
by the project via `@(AndroidLibrary)` or `@(EmbeddedJar)`.  It is
suggested that you *do not* have `publi` Java types which use Java
generics.  As with normal bindings, Java generics can cause
significant problems; try to stuck to normal types if you can.

[jonpryor]

@dellis1972: I don't see any way to get useful parameter names into the bindings. We had previous suggested using <JavaSourceUtils/> to extract parameter names:

xamarin-android/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.ClassParse.targets

Lines 70 to 88 in d260d03

	<Target Name="_ExtractJavadocsFromJavaSourceJars"
	Condition=" '$(_UseLegacyJavadocImport)' != 'True' And '@(JavaSourceJar->Count())' != '0' "
	DependsOnTargets="_GetJavaSourceJarJavadocFiles"
	Inputs="@(JavaSourceJar)"
	Outputs="@(_JavaSourceJavadocXml)">
	<JavaSourceUtils
	ContinueOnError="True"
	JavaSourceUtilsJar="$(AndroidJavaSourceUtilsJar)"
	InputFiles="%(_JavaSourceJavadocXml.OriginalItemSpec)"
	JavadocCopyrightFile="%(_JavaSourceJavadocXml.CopyrightFile)"
	JavadocUrlPrefix="%(_JavaSourceJavadocXml.UrlPrefix)"
	JavadocUrlStyle="%(_JavaSourceJavadocXml.UrlStyle)"
	JavadocDocRootUrl="%(_JavaSourceJavadocXml.DocRootUrl)"
	JavaMaximumHeapSize="$(JavaMaximumHeapSize)"
	JavaOptions="$(JavaOptions)"
	JavaSdkDirectory="$(_JavaSdkDirectory)"
	OutputJavadocXml="%(_JavaSourceJavadocXml.Identity)"
	References="@(JavaSourceJar)"
	/>

Alternatively, we could update the <Javac/> task to use javac -parameters.

However, I don't see either of these options here.

Are we doing anything to import parameter names?

[dellis1972]

Are we doing anything to import parameter names?

We talked about this and I seem to remember we decided to do this at a later date, cos this PR was large enough already.