Copied and adjusted from:

  * https://github.com/dotnet/runtime/blob/b443b8ccce174ef0e87183e21561c4ff13373cfd/SECURITY.md

@moljac pointed out that if you have invalid XPath in your metadata,
we simply error with the unhelpful:

	"generator.exe" exited with code -XXXXXX

![before](https://user-images.githubusercontent.com/179295/119032575-f4891680-b971-11eb-9580-96cc2e96e4aa.png)

If you turn on `Diagnostic` logs, you can see the uncaught exception
hiding in a lot of ceremony:

	message BG0000: Unhandled Exception: Java.Interop.Tools.Generator.BindingGeneratorException:
	  C:\code\temp\xamarin.exoplayer\Xamarin.ExoPlayer.Core\Transforms\Metadata.xml(11, 4):
	  error BG4304: Invalid XPath specification: /api/package[@name='com.google.android.exoplayer2']interface[@name='ExoPlayer']/method[@name='addMediaItems' and count(parameter)=2 and parameter[1][@type='int'] and parameter[2][@type='java.util.List<com.google.android.exoplayer2.source.MediaSource>']]/parameter[2].
	  ---> System.Xml.XPath.XPathException: '/api/package[@name='com.google.android.exoplayer2']interface[@name='ExoPlayer']/method[@name='addMediaItems' and count(parameter)=2 and parameter[1][@type='int'] and parameter[2][@type='java.util.List<com.google.android.exoplayer2.source.MediaSource>']]/parameter[2]' has an invalid token.
	message BG0000:    at MS.Internal.Xml.XPath.XPathParser.ParseXPathExpresion(String xpathExpresion)
	message BG0000:    at System.Xml.XPath.XPathExpression.Compile(String xpath, IXmlNamespaceResolver nsResolver)
	message BG0000:    at System.Xml.XPath.XPathNavigator.Evaluate(String xpath, IXmlNamespaceResolver resolver)
	message BG0000:    at System.Xml.XPath.XPathEvaluator.Evaluate[T](XNode node, String expression, IXmlNamespaceResolver resolver)
	message BG0000:    at System.Xml.XPath.Extensions.XPathSelectElements(XNode node, String expression, IXmlNamespaceResolver resolver)
	message BG0000:    at Java.Interop.Tools.Generator.FixupXmlDocument.Apply(ApiXmlDocument apiDocument, String apiLevelString, Int32 productVersion)
	message BG0000:    --- End of inner exception stack trace --- (TaskId:46)
	message BG0000:    at Java.Interop.Tools.Generator.Report.LogCodedError(LocalizedMessage message, Exception innerException, String sourceFile, Int32 line, Int32 column, String[] args)
	message BG0000:    at Java.Interop.Tools.Generator.Report.LogCodedError(LocalizedMessage message, Exception innerException, XNode node, String[] args)
	message BG0000:    at Java.Interop.Tools.Generator.FixupXmlDocument.Apply(ApiXmlDocument apiDocument, String apiLevelString, Int32 productVersion)
	message BG0000:    at Java.Interop.Tools.Generator.ApiXmlDocument.ApplyFixupFile(FixupXmlDocument fixup)
	message BG0000:    at Xamarin.Android.Binder.CodeGenerator.Run(CodeGeneratorOptions options, DirectoryAssemblyResolver resolver)
	message BG0000:    at Xamarin.Android.Binder.CodeGenerator.Run(CodeGeneratorOptions options)
	message BG0000:    at Xamarin.Android.Binder.CodeGenerator.Main(String[] args)
	error MSB6006: "generator.exe" exited with code -532462766.


It turns out this happens anywhere we throw a
`BindingGeneratorException`, as there is no `catch` handler that
attempts to gracefully handles this exception.

This led to making several improvements:

  - Gracefully handle `BindingGeneratorException` such that we print
    out the error as a standard MSBuild error that can be processed
    by Visual Studio.

  - Exit `generator` with `-1` if `BindingGeneratorException` is thrown.

  - Add a separate `Report.LogCodedError(…)` method called
    `Report.LogCodeErrorAndExit(…)`, which is used for terminal errors
    ("don't do any further processing and exit").

  - Audit existing calls to `Report.LogCodedError()` to allow errors
    such as `Invalid XPath` to be non-terminal.
    (Today `generator` will exit after finding the first one.)

  - Remove spaces in the error file location: `metadata.xml(8, 4): `
    becomes `metadata.xml(8,4):`.
    
    These were not being processed correctly and could not be double
    clicked in VS previously.

The result is a more useful error message:

	Metadata.xml(11,4): error BG4304: Invalid XPath specification …

We also now handle any unhandled exception a little better.

Additionally, `ApiFixup.cs` was deleted as it was no longer used after
the refactor in commit f4e68b5.

We've been seeing a NuGet restore error when running `make prepare`
on a macOS systems with .NET 6 Preview 4 (or greater) installed:

	Restoring packages for /Users/peter/source/java.interop/tools/logcat-parse/logcat-parse.csproj...
	NU1202: Package Mono.CSharp 4.0.0.143 is not compatible with net6.0 (.NETCoreApp,Version=v6.0). Package Mono.CSharp 4.0.0.143 supports: net45 (.NETFramework,Version=v4.5)
	…
	Errors in /Users/peter/source/java.interop/tools/logcat-parse/logcat-parse.csproj
	    NU1202: Package Mono.CSharp 4.0.0.143 is not compatible with net6.0 (.NETCoreApp,Version=v6.0). Package Mono.CSharp 4.0.0.143 supports: net45 (.NETFramework,Version=v4.5)

This error does not manifest when restoring or building with older
.NET 6 previews.

This issue is no longer present in a newer version of Mono 6.12 which
includes MSBuild 16.10.

Fix the error by provisioning Mono 6.12.0.145.

Context: #850

When a parsing issue is hit when importing Javadoc info, an "error"
is printed out like this:

	Error (31:41): Syntax error, expected: #PCDATA, <tt>, <TT>, <i>, <I>, {@code, {@docroot}, {@inheritdoc}, {@link, {@linkplain, {@literal, {@value}, {@value, UnknownHtmlElementStart, </tt>, </TT>, </i>, </I>, </p>, </P>, <p>, <P>, <pre>, <PRE>, @author, @apiSince, @deprecated, @deprecatedSince, @exception, @param, @return, @see, @Serialdata, @serialField, @SInCE, @throws, @[unknown], @Version
	    {@link #getCurrentTrackSelections()}}.</li>

This is intended to be informational, but this output format triggers
the MSBuild error parsing regex, and is interpreted as an actual
error, causing the build to fail.

Avoid the error by prepending `JavadocImport-` to the
`LogMessage.Level` enum value, so that MSBuild doesn't interpret the
string as an error and the build can successfully complete:

	JavadocImport-Error (31:41): Syntax error, expected: #PCDATA, <tt>, <TT>, <i>, <I>, {@code, {@docroot}, {@inheritdoc}, {@link, {@linkplain, {@literal, {@value}, {@value, UnknownHtmlElementStart, </tt>, </TT>, </i>, </I>, </p>, </P>, <p>, <P>, <pre>, <PRE>, @author, @apiSince, @deprecated, @deprecatedSince, @exception, @param, @return, @see, @Serialdata, @serialField, @SInCE, @throws, @[unknown], @Version
	    {@link #getCurrentTrackSelections()}}.</li>

)

Revert commit 4ef5081.

Fixes: #854

Context: 4ef5081
Context: #826

[As noted][0] in [PR #827][1], there is some "weirdness" with what
appears in the [`InnerClasses` collection][2].  It turns out this is
due to a misunderstanding of what the `InnerClasses` collection
contains.

As per the [docs][2]]:

> If a class has members that are classes or interfaces, its
> `constant_pool` table (and hence its `InnerClasses` attribute) must
> refer to each such member, even if that member is not otherwise
> mentioned by the class.
> **These rules imply that a nested class or interface member will
> have `InnerClasses` information for each enclosing class and for
> each immediate member.**

(Emphasis added.)  That is, the `PagedList$Config$Builder$Companion`
class lists *both* its immediate containing type
`PagedList$Config$Builder` and the "parent-parent" containing type
`PagedList$Config` within `InnerClasses`.

The change made in commit 4ef5081 loops through `InnerClasses`,
marking them as `internal`, assuming they are all nested types.
This is causing us to hide *declaring* types when we are trying to
hide *nested* types.

This will require more investigation and the deadline for 16.11 is
~now, so we're just going to revert the original commit.

[0]: #827 (comment)
[1]: #827
[2]: https://docs.oracle.com/javase/specs/jvms/se7/html/jvms-4.html#jvms-4.7.6

Context: #850 (comment)

When a user binds a Java library that contains a Java interface which
implements another Java interface:

	// Java; android.jar
	public interface /* android.view. */ Menu {…}

	// Java; androidx.core.core.jar
	public interface /* androidx.core.internal.view. */ SupportMenu implements android.view.Menu {…}

then when we create the binding for the "leaf" interface:

	// C# binding for androidx.core.core
	namespace AndroidX.Core.Internal.View {
	    public interface ISupportMenu : Android.Views.IMenu {…}

	    internal partial class ISupportMenuInvoker : Java.Lang.Object, ISupportMenu {
	        // …
	    }
	}

The generated `*Invoker` type implements all methods for all
implemented interfaces, e.g. methods from both `IMenu` and
`ISupportMenu`.

When:

 1. The base interface (e.g. `IMenu`) comes from a referenced
    assembly, *and*

 2. `$(Nullable)`=Enable when binding the derived interface

then we interpret the return types on imported interface methods as
*always* being of a nullable type, even for types such as `void`:

	// C# binding for androidx.core.core with $(Nullable)=Enable
	partial class ISupportMenuInvoker : Java.Lang.Object, ISupportMenu {

	    public unsafe void? Clear () {…}
	}

This results in errors from the C# compiler:

	Error CS1519: Invalid token '?' in class, record, struct, or interface member declaration
	Error CS1520: Method must have a return type
	Error CS0535: 'ISupportMenuInvoker' does not implement interface member 'IMenu.Clear()'

The culprit is twofold:

  - In `CecilApiImporter`, we set `Method.ManagedReturn` to
    `System.Void` instead of `void`.

  - In `CodeGenerationOptions`, we only check for `void` to omit the
    null operator, not `System.Void`.

Note this also happens for all primitive types like
`System.Int32`/`int`.

This commit fixes both aspects:

  - Change `Method.ManagedReturn` to contain primitive types instead
    of fully qualified types.

  - Update `CodeGenerationOptions.GetNullable()` to correctly handle
    fully qualified types if one slips through.

With this change, all of AndroidX/GooglePlayServices/FaceBook/MLKit
can be successfully compiled with `<Nullable>enable</Nullable>`.

Context: dotnet/sdk#19050

xamarin-android is hitting this build error with .NET 6 Preview 7:

    C:\src\xamarin-android\external\Java.Interop\src\Java.Interop\obj\Debug\net6.0\Java.Interop.ImplicitNamespaceImports.cs(2,1):
    error CS8400: Feature 'global using directive' is not available in C# 8.0. Please use language version 10.0 or greater.
    [C:\src\xamarin-android\external\Java.Interop\src\Java.Interop\Java.Interop.csproj]

In fact, you can reproduce this by doing:

    dotnet new console
    dotnet build -p:LangVersion=8.0

It seems like `@(Import)` item group should not be present unless the
project is C# 10 or higher?

For now, we can set `$(DisableImplicitNamespaceImports)` to workaround
the issue.