[generator] Add Java.Interop.Tools.JavaTypeSystem (#849)

Fixes: #739
Fixes: #852
Fixes: #853

Context: #789
Context: #814
Context: #815

Today, we use a process called `ApiXmlAdjuster` to convert our "new"
`class-parse` format to the old `jar2xml` format.  This process
attempts to resolve every Java type referenced by the library we
intend to bind.  However, performing this as a separate step has
some disadvantages:

  - It duplicates work by reading in `api.xml.class-parse`
    and Cecil'ing all reference assemblies, then writing it back out
    as `api.xml`.
    `generator` then reads in `api.xml` and Cecils all the reference
    assemblies again.

  - This work is performed as a separate step before `generator` and
    thus cannot be influenced by `metadata`.

  - This work is cached, which is "good", but it creates issues for
    users because they only see warnings from it for full Rebuilds.

"Replace" `ApiXmlAdjuster` with `Java.Interop.Tools.JavaTypeSystem`,
which is a much more robust Java model to perform this work, and
contains enough information to be reused by `generator`.
This prevents us from needing to have a second Java and Cecil import
step, and we can run `metadata` directly on `api.xml.class-parse`
before the import.

NOTE: This commit sets the groundwork for the above benefits, but
does not achieve them yet.  Initially we are only focused on
achieving parity with `ApiXmlAdjuster` to make correctness
comparisons possible.

The new `JavaTypeSystem` infrastructure is used by default; the
previous `ApiXmlAdjuster` system can be used instead by using:

	generator --use-legacy-java-resolver=true …

We will provide an MSBuild property to control this when we integrate
with xamarin-android in the future.


~~ Warning Messages ~~

In order to better surface potentially real errors to users, we have
tweaked the warnings displayed.  Errors we encounter during the
initial phase of Java type resolution are emitted as warnings.
These are missing external Java types and generally indicate the user
is missing a reference `.jar` or binding NuGet:

	warning BG8605: The Java type 'androidx.appcompat.widget.AppCompatTextView' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)

The remaining resolution errors are generally the fallout from those
missing external types.  For example, if the above missing type
caused us to remove `com.example.MyTextView`, then that may result in
us removing the method `GetMyTextView()` due to a missing return type.

Today these messages are only displayed in a Diagnostic log and are
often missed.  Instead, we are going to write them to a log file
called `java-resolution-report.log`, and then display a warning
notifying the user that some types could not be bound, which can be
double clicked to view the log file.

	warning BG8606: Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.

Example `java-resolution-report.log`:

	==== Cycle 1 ====

	'[Class] com.example.MyTextView' was removed because the Java type 'androidx.appcompat.widget.AppCompatTextView' could not be found.

	==== Cycle 2 ====

	'[Method] com.example.MyActivity.getMyTextView' was removed because the Java type 'com.example.MyTextView' could not be found.


"Cycles" represent the passes through the type collection when
resolving the collection.  For example:

  - Cycle 1 removed type `com.example.MyType` because its external
    base type `android.util.List` was missing

  - Cycle 2 removed type `com.example.MyDerivedType` because its base
    type `com.example.MyType` is now missing

  - Cycle 3 removed method `com.example.Foo.getBar()` because it
    returns `com.example.MyDerivedType`, which is now missing

This distinction can be interesting, because Cycle 1 removals are
generally due to missing `.jar` dependencies, whereas the remaining
cycles are just the internal fallout from previous cycles, which will
largely be fixed by fixing the first cycle issues.


~~ Additional Fixes ~~

There are several issues with the `ApiXmlAdjuster` process that *can*
be fixed by this change.  For the initial purpose of being able to
verify that we produce the same output, these have been disabled in
the new `JavaTypeSystem` code.

  * [ApiXmlAdjuster removes required methods from interfaces][0] -
    Currently disabled via flag
    `TypeResolutionOptions.RemoveInterfacesWithUnresolvableMembers`.

  * [ApiXmlAdjuster fails to resolve parent type parameters for nested types][1] -
    Currently commented out in `JavaTypeModel.GetApplicableTypeParameters()`.

  * [ApiXmlAdjuster doesn't remove nested types][2] -
    Currently enabled, compares have been done with a custom
    `ApiXmlAdjuster` where this has been fixed.

  * [ApiXmlAdjuster prefers JavaList over ArrayList][3] -
    Currently enabled, compares have been done with a custom
    `ApiXmlAdjuster` where this has been fixed.


~~ Performance ~~

Although performance isn't really a focus, there are wins here as well,
largely due to only resolving reference types that are actually
referenced.  Example: `ApiXmlAdjuster` fully resolves all 5K+ types in
`Mono.Android.dll`, while `JavaTypeSystem` only resolves the ones
needed by the library being bound.

Time to resolve `androidx.appcompat.appcompat`:

  * ApiXmlAdjuster: 2849ms
  * JavaTypeSystem: 1514ms


~~ Testing ~~

  - Unit tests have been ported from `ApiXmlAdjuster-Tests`
  - Tested for identical output for 136 current AndroidX packages
  - Tested for identical output for 140 current GPS/FB packages

Note `Mono.Android.dll` does not use `ApiXmlAdjuster`, so no testing
was performed with it.

[0]: #814
[1]: #815
[2]: #852
[3]: #853

Author: jpobst

Java.Interop.sln

@@ -101,6 +101,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "invocation-overhead", "test
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "NativeTiming", "tests\NativeTiming\NativeTiming.csproj", "{BF5A4019-F2FF-45AC-949D-EF7E8C94196B}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Java.Interop.Tools.JavaTypeSystem", "src\Java.Interop.Tools.JavaTypeSystem\Java.Interop.Tools.JavaTypeSystem.csproj", "{B173F53B-986C-4E0D-881C-063BBB116E1D}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Java.Interop.Tools.JavaTypeSystem-Tests", "tests\Java.Interop.Tools.JavaTypeSystem-Tests\Java.Interop.Tools.JavaTypeSystem-Tests.csproj", "{11942DE9-AEC2-4B95-87AB-CA707C37643D}"
+EndProject
 Global
 	GlobalSection(SharedMSBuildProjectFiles) = preSolution
 		src\Java.Interop.NamingCustomAttributes\Java.Interop.NamingCustomAttributes.projitems*{58b564a1-570d-4da2-b02d-25bddb1a9f4f}*SharedItemsImports = 5
@@ -284,6 +288,14 @@ Global
 		{BF5A4019-F2FF-45AC-949D-EF7E8C94196B}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{BF5A4019-F2FF-45AC-949D-EF7E8C94196B}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{BF5A4019-F2FF-45AC-949D-EF7E8C94196B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{B173F53B-986C-4E0D-881C-063BBB116E1D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{B173F53B-986C-4E0D-881C-063BBB116E1D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{B173F53B-986C-4E0D-881C-063BBB116E1D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{B173F53B-986C-4E0D-881C-063BBB116E1D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{11942DE9-AEC2-4B95-87AB-CA707C37643D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{11942DE9-AEC2-4B95-87AB-CA707C37643D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{11942DE9-AEC2-4B95-87AB-CA707C37643D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{11942DE9-AEC2-4B95-87AB-CA707C37643D}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -332,6 +344,8 @@ Global
 		{998D178B-F4C7-48B5-BDEE-44E2F869BB22} = {0998E45F-8BCE-4791-A944-962CD54E2D80}
 		{3CF58D34-693C-408A-BFE7-BC5E4BE44A26} = {271C9F30-F679-4793-942B-0D9527CB3E2F}
 		{BF5A4019-F2FF-45AC-949D-EF7E8C94196B} = {271C9F30-F679-4793-942B-0D9527CB3E2F}
+		{B173F53B-986C-4E0D-881C-063BBB116E1D} = {0998E45F-8BCE-4791-A944-962CD54E2D80}
+		{11942DE9-AEC2-4B95-87AB-CA707C37643D} = {271C9F30-F679-4793-942B-0D9527CB3E2F}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {29204E0C-382A-49A0-A814-AD7FBF9774A5}

src/Java.Interop.Localization/Resources.Designer.cs

@@ -253,6 +253,14 @@ The following terms should not be translated: &lt;package&gt;.</comment>
     <value>Could not find top ancestor type '{0}' for nested type '{1}'.</value>
     <comment>{0}, {1} - .NET types.</comment>
   </data>
+  <data name="Generator_BG8605" xml:space="preserve">
+    <value>The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</value>
+    <comment>{0} - Java type.</comment>
+  </data>
+  <data name="Generator_BG8606" xml:space="preserve">
+    <value>Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</value>
+    <comment>The following terms should not be translated: java-resolution-report.log</comment>
+  </data>
   <data name="Generator_BG8700" xml:space="preserve">
     <value>Unknown return type '{0}' for member '{1}'.</value>
     <comment>{0} - Java type.

src/Java.Interop.Localization/Resources.resx

@@ -167,6 +167,16 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <target state="new">Could not find top ancestor type '{0}' for nested type '{1}'.</target>
         <note>{0}, {1} - .NET types.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8605">
+        <source>The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</source>
+        <target state="new">The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</target>
+        <note>{0} - Java type.</note>
+      </trans-unit>
+      <trans-unit id="Generator_BG8606">
+        <source>Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</source>
+        <target state="new">Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</target>
+        <note>The following terms should not be translated: java-resolution-report.log</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8700">
         <source>Unknown return type '{0}' for member '{1}'.</source>
         <target state="new">Unknown return type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.cs.xlf

@@ -167,6 +167,16 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <target state="new">Could not find top ancestor type '{0}' for nested type '{1}'.</target>
         <note>{0}, {1} - .NET types.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8605">
+        <source>The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</source>
+        <target state="new">The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</target>
+        <note>{0} - Java type.</note>
+      </trans-unit>
+      <trans-unit id="Generator_BG8606">
+        <source>Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</source>
+        <target state="new">Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</target>
+        <note>The following terms should not be translated: java-resolution-report.log</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8700">
         <source>Unknown return type '{0}' for member '{1}'.</source>
         <target state="new">Unknown return type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.de.xlf

@@ -167,6 +167,16 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <target state="new">Could not find top ancestor type '{0}' for nested type '{1}'.</target>
         <note>{0}, {1} - .NET types.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8605">
+        <source>The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</source>
+        <target state="new">The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</target>
+        <note>{0} - Java type.</note>
+      </trans-unit>
+      <trans-unit id="Generator_BG8606">
+        <source>Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</source>
+        <target state="new">Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</target>
+        <note>The following terms should not be translated: java-resolution-report.log</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8700">
         <source>Unknown return type '{0}' for member '{1}'.</source>
         <target state="new">Unknown return type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.es.xlf

@@ -167,6 +167,16 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <target state="new">Could not find top ancestor type '{0}' for nested type '{1}'.</target>
         <note>{0}, {1} - .NET types.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8605">
+        <source>The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</source>
+        <target state="new">The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</target>
+        <note>{0} - Java type.</note>
+      </trans-unit>
+      <trans-unit id="Generator_BG8606">
+        <source>Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</source>
+        <target state="new">Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</target>
+        <note>The following terms should not be translated: java-resolution-report.log</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8700">
         <source>Unknown return type '{0}' for member '{1}'.</source>
         <target state="new">Unknown return type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.fr.xlf

@@ -167,6 +167,16 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <target state="new">Could not find top ancestor type '{0}' for nested type '{1}'.</target>
         <note>{0}, {1} - .NET types.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8605">
+        <source>The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</source>
+        <target state="new">The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</target>
+        <note>{0} - Java type.</note>
+      </trans-unit>
+      <trans-unit id="Generator_BG8606">
+        <source>Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</source>
+        <target state="new">Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</target>
+        <note>The following terms should not be translated: java-resolution-report.log</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8700">
         <source>Unknown return type '{0}' for member '{1}'.</source>
         <target state="new">Unknown return type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.it.xlf

@@ -167,6 +167,16 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <target state="new">Could not find top ancestor type '{0}' for nested type '{1}'.</target>
         <note>{0}, {1} - .NET types.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8605">
+        <source>The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</source>
+        <target state="new">The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</target>
+        <note>{0} - Java type.</note>
+      </trans-unit>
+      <trans-unit id="Generator_BG8606">
+        <source>Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</source>
+        <target state="new">Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</target>
+        <note>The following terms should not be translated: java-resolution-report.log</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8700">
         <source>Unknown return type '{0}' for member '{1}'.</source>
         <target state="new">Unknown return type '{0}' for member '{1}'.</target>

src/Java.Interop.Localization/xlf/Resources.ja.xlf

@@ -167,6 +167,16 @@ The following terms should not be translated: &lt;package&gt;.</note>
         <target state="new">Could not find top ancestor type '{0}' for nested type '{1}'.</target>
         <note>{0}, {1} - .NET types.</note>
       </trans-unit>
+      <trans-unit id="Generator_BG8605">
+        <source>The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</source>
+        <target state="new">The Java type '{0}' could not be found (are you missing a Java reference jar/aar or a Java binding library NuGet?)</target>
+        <note>{0} - Java type.</note>
+      </trans-unit>
+      <trans-unit id="Generator_BG8606">
+        <source>Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</source>
+        <target state="new">Some types or members could not be bound because referenced Java types could not be found. See the 'java-resolution-report.log' file for details.</target>
+        <note>The following terms should not be translated: java-resolution-report.log</note>
+      </trans-unit>
       <trans-unit id="Generator_BG8700">
         <source>Unknown return type '{0}' for member '{1}'.</source>
         <target state="new">Unknown return type '{0}' for member '{1}'.</target>