[Xamarin.Android.Build.Tasks] Enable POM verification features. (#8649)

Fixes: #4528 Context: 3659766 Context: dotnet/java-interop@1c9c8c9 Commit 3659766 mentioned: > There are 2 parts to #4528: > > 1. Downloading artifacts from Maven > 2. Ensuring all dependencies specified in the POM file are met > > Only (1) is currently addressed. (2) will be addressed in the future. Implement support for (2): use `Java.Interop.Tools.Maven.dll` from dotnet/java-interop@1c9c8c9c to download and parse [Maven POM files][0] and ensure that all required Java dependencies are fulfilled. POM files are downloaded into `$(MavenCacheDirectory)` (3659766). Java dependency verification is a critical step that users often miss or make mistakes, resulting in non-functional bindings. Consider a classlib project with the following snippet: <ItemGroup> <AndroidMavenLibrary Include="com.squareup.okhttp3:okhttp" Version="4.9.3" /> </ItemGroup> With the new POM verification features, the above snippet will produce the following errors: error XA4242: Java dependency 'com.squareup.okio:okio:2.8.0' is not satisfied. Microsoft maintains the NuGet package 'Square.OkIO' that could fulfill this dependency. error XA4242: Java dependency 'org.jetbrains.kotlin:kotlin-stdlib:1.4.10' is not satisfied. Microsoft maintains the NuGet package 'Xamarin.Kotlin.StdLib' that could fulfill this dependency. This is accomplished by automatically downloading the POM file (and any needed parent/imported POM files) for the specified artifact and using them to determine all required dependencies. There are many documented ways of fixing these errors, the best way is using the latest versions of the suggested NuGet packages: <ItemGroup> <PackageReference Include="Square.OkIO" Version="3.6.0.1" /> <PackageReference Include="Xamarin.Kotlin.StdLib" Version="1.9.22" /> </ItemGroup> Note this commit replaces our previous usage of `MavenNet` with `Java.Interop.Tools.Maven`. Thus it removes the `MavenNet` TPN. Some future concerns: - Can we automatically determine which dependencies are met by a `@(ProjectReference)`? Today, the user must manually add the metadata `%(ProjectReference.JavaArtifact)` and `%(ProjectReference.JavaVersion)` to specify this. - We use the link https://aka.ms/ms-nuget-packages to download [`microsoft-packages.json`][1], which is used to provide NuGet suggestions. We need to figure out a permanent home for this file and a process for generating it. Luckily we can ship a preview for now and change the `aka.ms` link to point to the permanent home later. [0]: https://maven.apache.org/pom.html [1]: https://raw.githubusercontent.com/jpobst/Prototype.Android.MavenBindings/main/microsoft-packages.json
dotnet · Mar 22, 2024 · 4696bf3 · 4696bf3
1 parent e206c52
commit 4696bf3
Show file tree

Hide file tree

Showing 35 changed files with 2,333 additions and 290 deletions.
diff --git a/Documentation/guides/AndroidMavenLibrary.md b/Documentation/guides/AndroidMavenLibrary.md
@@ -17,9 +17,10 @@ Note: This feature is only available in .NET 9+.
 </ItemGroup>
 ```
 
-This will do two things at build time:
+This will do several things at build time:
 - Download the Java [artifact](https://central.sonatype.com/artifact/com.squareup.okhttp3/okhttp/4.9.3) with group id `com.squareup.okhttp3`, artifact id `okhttp`, and version `4.9.3` from [Maven Central](https://central.sonatype.com/) to a local cache (if not already cached).
 - Add the cached package to the .NET Android bindings build as an [`<AndroidLibrary>`](https://github.com/xamarin/xamarin-android/blob/main/Documentation/guides/building-apps/build-items.md#androidlibrary).
+- Download the Java artifact's POM file (and any needed parent/imported POM files) to enable [Java Dependency Verification](JavaDependencyVerification.md). To opt out of this feature, add `VerifyDependencies="false"` to the `<AndroidMavenLibrary>` item.
 
 Note that only the requested Java artifact is added to the .NET Android bindings build. Any artifact dependencies are not added. If the requested artifact has dependencies, they must be fulfilled individually.
 

diff --git a/Documentation/guides/JavaDependencyVerification.md b/Documentation/guides/JavaDependencyVerification.md
@@ -0,0 +1,115 @@
+# Java Dependency Verification
+
+Note: This feature is only available in .NET 9+.
+
+## Description
+
+A common problem when creating Java binding libraries for .NET Android is not providing the required Java dependencies. The binding process ignores API that requires missing dependencies, so this can result in large portions of desired API not being bound.
+
+Unlike .NET assemblies, a Java library does not specify its dependencies in the package. The dependency information is stored in external files called POM files. In order to consume this information to ensure correct dependencies an additional layer of files must be added to a binding project.
+
+Note: the preferred way of interacting with this system is to use [`<AndroidMavenLibrary>`](AndroidMavenLibrary.md) which will automatically download any needed POM files.
+
+For example:
+
+```xml
+<AndroidMavenLibrary Include="com.squareup.okio:okio" Version="1.17.4" />
+```
+
+automatically gets expanded to:
+
+```xml
+<AndroidLibrary 
+  Include="<MavenCacheDir>/Central/com.squareup.okio/okio/1.17.4/com.squareup.okio_okio.jar" 
+  Manifest="<MavenCacheDir>/Central/com.squareup.okio/okio/1.17.4/com.squareup.okio_okio.pom"
+  JavaArtifact="com.squareup.okio:okio" 
+  JavaVersion="1.17.4" />
+
+<AndroidAdditionalJavaManifest
+  Include="<MavenCacheDir>/Central/com.squareup.okio/okio-parent/1.17.4/okio-parent-1.17.4.pom"
+  JavaArtifact="com.squareup.okio:okio-parent"
+  JavaVersion="1.17.4" />
+
+etc.
+```
+
+However it is also possible to manually opt in to Java dependency verification using the build items documented here.
+
+## Specification
+
+To manually opt in to Java dependency verification, add the `Manifest`, `JavaArtifact`, and `JavaVersion` attributes to an `<AndroidLibrary>` item:
+
+```xml
+<!-- JavaArtifact format is {GroupId}:{ArtifactId} -->
+<ItemGroup>
+  <AndroidLibrary
+    Include="my_binding_library.jar"
+    Manifest="my_binding_library.pom"
+    JavaArtifact="com.example:mybinding"
+    JavaVersion="1.0.0" />
+</ItemGroup>
+```
+
+Building the binding project now should result in verification errors if `my_binding_library.pom` specifies dependencies that are not met.
+
+For example:
+
+```
+error : Java dependency 'androidx.collection:collection' version '1.0.0' is not satisfied.
+```
+
+Seeing these error(s) or no errors should indicate that the Java dependency verification is working. Follow the [Resolving Java Dependencies](ResolvingJavaDependencies.md) guide to fix any missing dependency errors.
+
+## Additional POM Files
+
+POM files can sometimes have some optional features in use that make them more complicated than the above example.
+
+That is, a POM file can depend on a "parent" POM file:
+
+```xml
+<parent>
+  <groupId>com.squareup.okio</groupId>
+  <artifactId>okio-parent</artifactId>
+  <version>1.17.4</version>
+</parent>
+```
+
+Additionally, a POM file can "import" dependency information from another POM file:
+
+```xml
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>com.squareup.okio</groupId>
+      <artifactId>okio-bom</artifactId>
+      <version>3.0.0</version>
+      <type>pom</type>
+      <scope>import</scope>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+```
+
+Dependency information cannot be accurately determined without also having access to these additional POM files, and will results in an error like:
+
+```
+error : Unable to resolve POM for artifact 'com.squareup.okio:okio-parent:1.17.4'.
+```
+
+In this case, we need to provide the POM file for `com.squareup.okio:okio-parent:1.17.4`:
+
+```xml
+<!-- JavaArtifact format is {GroupId}:{ArtifactId} -->
+<ItemGroup>
+  <AndroidAdditionalJavaManifest
+    Include="com.square.okio.okio-parent.1.17.4.pom"
+    JavaArtifact="com.squareup.okio:okio-parent"
+    JavaVersion="1.17.4" />
+</ItemGroup>
+```
+
+Note that as "Parent" and "Import" POMs can themselves have parent and imported POMs, this step may need to be repeated until all POM files can be resolved.
+
+Note also that if using `<AndroidMavenLibrary>` this should all be handled automatically.
+
+At this point, if there are dependency errors, follow the [Resolving Java Dependencies](ResolvingJavaDependencies.md) guide to fix any missing dependency errors.
diff --git a/Documentation/guides/ResolvingJavaDependencies.md b/Documentation/guides/ResolvingJavaDependencies.md
@@ -0,0 +1,101 @@
+# Resolving Java Dependencies
+
+Note: This feature is only available in .NET 9+.
+
+## Description
+
+Once Java dependency verification has been enabled for a bindings project, either automatically via `<AndroidMavenLibrary>` or manually via `<AndroidLibrary>`, there may be errors to resolve, such as:
+
+```
+error : Java dependency 'androidx.collection:collection' version '1.0.0' is not satisfied.
+```
+
+These dependencies can be fulfilled in many different ways.
+
+## `<PackageReference>`
+
+In the best case scenario, there is already an existing binding of the Java dependency available on NuGet.org. This package may be provided by Microsoft or the .NET community. Packages maintained by Microsoft may be surfaced in the error message like this:
+
+```
+error : Java dependency 'androidx.collection:collection' version '1.0.0' is not satisfied. Microsoft maintains the NuGet package 'Xamarin.AndroidX.Collection' that could fulfill this dependency.
+```
+
+Adding the `Xamarin.AndroidX.Collection` package to the project should automatically resolve this error, as the package provides metadata to advertise that it provides the `androidx.collection:collection` dependency. This is done by looking for a specially crafted NuGet tag.  For example, for the AndroidX Collection library, the tag looks like this:
+
+```xml
+<!-- artifact={GroupId}:{ArtifactId}:{Java Library Version} -->
+<PackageTags>artifact=androidx.collection:collection:1.0.0</PackageTags>
+```
+
+However there may be NuGet packages which fulfill a dependency but have not had this metadata added to it.  In this case, you will need to explicitly specify which dependency the package contains with `JavaArtifact` and `JavaVersion`:
+
+```xml
+<PackageReference 
+  Include="Xamarin.Kotlin.StdLib" 
+  Version="1.7.10" 
+  JavaArtifact="org.jetbrains.kotlin:kotlin-stdlib" 
+  JavaVersion="1.7.10" />
+```
+
+With this, the binding process knows the Java dependency is satisfied by the NuGet package.
+
+> Note: NuGet packages specify their own dependencies, so you will not need to worry about transitive dependencies.
+
+## `<ProjectReference>`
+
+If the needed Java dependency is provided by another project in your solution, you can annotate the `<ProjectReference>` to specify the dependency it fulfills:
+
+```xml
+<ProjectReference 
+  Include="..\My.Other.Binding\My.Other.Binding.csproj" 
+  JavaArtifact="my.other.binding:helperlib" 
+  JavaVersion="1.0.0" />
+```
+
+With this, the binding process knows the Java dependency is satisfied by the referenced project.
+
+> Note: Each project specifies their own dependencies, so you will not need to worry about transitive dependencies.
+
+## `<AndroidLibrary>`
+
+If you are creating a public NuGet package, you will want to follow NuGet's "one library per package" policy so that the NuGet dependency graph works.  However, if creating a binding for private use, you may want to include your Java dependencies directly inside the parent binding.
+
+This can be done by adding additional `<AndroidLibrary>` items to the project:
+
+```xml
+<ItemGroup>
+  <AndroidLibrary Include="mydependency.jar" JavaArtifact="my.library:dependency-library" JavaVersion="1.0.0" />
+</ItemGroup>
+```
+
+To include the Java library but not produce C# bindings for it, mark it with `Bind="false"`:
+
+```xml
+<ItemGroup>
+  <AndroidLibrary Include="mydependency.jar" JavaArtifact="my.library:dependency-library" JavaVersion="1.0.0" Bind="false" />
+</ItemGroup>
+```
+
+Alternatively, `<AndroidMavenLibrary>` can be used to retrieve a Java library from a Maven repository:
+
+```xml
+<ItemGroup>
+  <AndroidMavenLibrary Include="my.library:dependency-library" Version="1.0.0" />
+  <!-- or, if the Java library doesn't need to be bound -->
+  <AndroidMavenLibrary Include="my.library:dependency-library" Version="1.0.0" Bind="false" />
+</ItemGroup>
+```
+
+> Note: If the dependency library has its own dependencies, you will be required to ensure they are fulfilled.
+
+## `<AndroidIgnoredJavaDependency>`
+
+As a last resort, a needed Java dependency can be ignored. An example of when this is useful is if the dependency library is a collection of Java annotations that are only used at compile type and not runtime.
+
+Note that while the error message will go away, it does not mean the package will magically work. If the dependency is actually needed at runtime and not provided the Android application will crash with a `Java.Lang.NoClassDefFoundError` error.
+
+```xml
+<ItemGroup>
+  <AndroidIgnoredJavaDependency Include="com.google.errorprone:error_prone_annotations" Version="2.15.0" />
+</ItemGroup>
+```
diff --git a/Documentation/guides/building-apps/build-items.md b/Documentation/guides/building-apps/build-items.md
@@ -14,6 +14,30 @@ ms.date: 07/26/2022
 Build items control how a Xamarin.Android application
 or library project is built.
 
+## AndroidAdditionalJavaManifest
+
+`<AndroidAdditionalJavaManifest>` is used in conjunction with [Java Dependency Resolution](../JavaDependencyVerification.md).
+
+It is used to specify additional POM files that will be needed to verify dependencies.
+These are often parent or imported POM files referenced by a Java library's POM file.
+
+```xml
+<ItemGroup>
+  <AndroidAdditionalJavaManifest Include="mylib-parent.pom" JavaArtifact="com.example:mylib-parent" JavaVersion="1.0.0" />
+</ItemGroup>
+```
+
+The following MSBuild metadata are required:
+
+- `%(JavaArtifact)`: The group and artifact id of the Java library matching the specifed POM
+  file in the form `{GroupId}:{ArtifactId}`.
+- `%(JavaVersion)`: The version of the Java library matching the specified POM file.
+
+See the [Java Dependency Resolution documentation](../JavaDependencyVerification.md)
+for more details.
+
+This build action was introduced in .NET 9.
+
 ## AndroidAsset
 
 Supports [Android Assets](https://developer.android.com/guide/topics/resources/providing-resources#OriginalFiles),
@@ -115,6 +139,30 @@ Files with a Build action of `AndroidJavaLibrary` are Java
 Archives ( `.jar` files) that will be included in the final Android
 package.
 
+## AndroidIgnoredJavaDependency
+
+`<AndroidIgnoredJavaDependency>` is used in conjunction with [Java Dependency Resolution](../JavaDependencyVerification.md).
+
+It is used to specify a Java dependency that should be ignored. This can be
+used if a dependency will be fulfilled in a way that Java dependency resolution
+cannot detect.
+
+```xml
+<!-- Include format is {GroupId}:{ArtifactId} -->
+<ItemGroup>
+  <AndroidIgnoredJavaDependency Include="com.google.errorprone:error_prone_annotations" Version="2.15.0" />
+</ItemGroup>
+```
+
+The following MSBuild metadata are required:
+
+- `%(Version)`: The version of the Java library matching the specified `%(Include)`.
+
+See the [Java Dependency Resolution documentation](../JavaDependencyVerification.md)
+for more details.
+
+This build action was introduced in .NET 9.
+
 ## AndroidJavaSource
 
 Files with a Build action of `AndroidJavaSource` are Java source code that
@@ -218,6 +266,17 @@ hosted in Maven.
   <AndroidMavenLibrary Include="com.squareup.okhttp3:okhttp" Version="4.9.3" />
 </ItemGroup>
 ```
+
+The following MSBuild metadata are supported:
+
+- `%(Version)`: Required version of the Java library referenced by `%(Include)`.
+- `%(Repository)`: Optional Maven repository to use. Supported values are `Central` (default),
+   `Google`, or an `https` URL to a Maven repository.
+
+The `<AndroidMavenLibrary>` item is translated to an 
+[`<AndroidLibrary>`](https://github.com/xamarin/xamarin-android/blob/main/Documentation/guides/building-apps/build-items.md#androidlibrary) 
+item, so any metadata supported by `<AndroidLibrary>` like `Bind` or `Pack` are also supported.
+
 See the [AndroidMavenLibrary documentation](../AndroidMavenLibrary.md)
 for more details.
 

diff --git a/Documentation/guides/messages/README.md b/Documentation/guides/messages/README.md
@@ -186,6 +186,19 @@ Either change the value in the AndroidManifest.xml to match the $(SupportedOSPla
 + XA4230: Error parsing XML: {exception}
 + [XA4231](xa4231.md): The Android class parser value 'jar2xml' is deprecated and will be removed in a future version of Xamarin.Android. Update the project properties to use 'class-parse'.
 + [XA4232](xa4232.md): The Android code generation target 'XamarinAndroid' is deprecated and will be removed in a future version of Xamarin.Android. Update the project properties to use 'XAJavaInterop1'.
++ [XA4234](xa4234.md): '<{item}>' item '{itemspec}' is missing required attribute '{name}'.
++ [XA4235](xa4235.md): Maven artifact specification '{artifact}' is invalid. The correct format is 'group_id:artifact_id'.
++ [XA4236](xa4236.md): Cannot download Maven artifact '{group}:{artifact}'. - {jar}: {exception} - {aar}: {exception}
++ [XA4237](xa4237.md): Cannot download POM file for Maven artifact '{artifact}'. - {exception}
++ [XA4239](xa4239.md): Unknown Maven repository: '{repository}'.
++ [XA4241](xa4241.md): Java dependency '{artifact}' is not satisfied.
++ [XA4242](xa4242.md): Java dependency '{artifact}' is not satisfied. Microsoft maintains the NuGet package '{nugetId}' that could fulfill this dependency.
++ [XA4243](xa4243.md): Attribute '{name}' is required when using '{name}' for '{element}' item '{itemspec}'.
++ [XA4244](xa4244.md): Attribute '{name}' cannot be empty for '{element}' item '{itemspec}'.
++ [XA4245](xa4245.md): Specified POM file '{file}' does not exist.
++ [XA4246](xa4246.md): Could not parse POM file '{file}'. - {exception}
++ [XA4247](xa4247.md): Could not resolve POM file for artifact '{artifact}'.
++ [XA4248](xa4248.md): Could not find NuGet package '{nugetId}' version '{version}' in lock file. Ensure NuGet Restore has run since this <PackageReference> was added.
 + XA4300: Native library '{library}' will not be bundled because it has an unsupported ABI.
 + [XA4301](xa4301.md): Apk already contains the item `xxx`.
 + [XA4302](xa4302.md): Unhandled exception merging \`AndroidManifest.xml\`: {ex}

diff --git a/Documentation/guides/messages/xa4234.md b/Documentation/guides/messages/xa4234.md
@@ -0,0 +1,34 @@
+---
+title: .NET Android error XA4234
+description: XA4234 error code
+ms.date: 02/26/2024
+---
+# .NET Android error XA4234
+
+## Example message
+
+```
+error XA4234: '<AndroidMavenLibrary>' item 'com.example:mylib' is missing required attribute 'Version'.
+```
+
+## Issue
+
+The specified MSBuild XML item requires the specified XML attribute.
+
+For example the following item is missing the required 'Version' attribute:
+
+```xml
+<ItemGroup>
+  <AndroidMavenLibrary Include="com.example:mylib" />
+</ItemGroup>
+```
+
+## Solution
+
+To resolve this error, ensure that the specified XML contains the specified attribute:
+
+```xml
+<ItemGroup>
+  <AndroidMavenLibrary Include="com.example:mylib" Version="1.0.0" />
+</ItemGroup>
+```