No description, website, or topics provided.
Clone or download
jonpryor [generator] Remove CS0108 warning for inherited methods (#412)
When a Java method is declared which has a name matching a method name
from a C# base class, a CS0108 warning is produced:

	Xamarin.Test.SomeObject.cs(77,31): warning CS0108:
	`Xamarin.Test.SomeObject.GetType()' hides inherited member `object.GetType()'.
	Use the new keyword if hiding was intended

Fix this by updating `GenBase.RequiresNew()` to have a more complete
set of member names from `System.Object` and `System.Exception`, and
calling `GenBase.RequiresNew()` from
`CodeGenerator.WriteMethodAbstractDeclaration()` so that `new` is
emitted for `GetType()` and other methods.

Additionally, the `NormalMethods.cs` test also contains obsolete
methods, which results in CS0618 warnings:

	Xamarin.Test.SomeObject.cs(317,18): warning CS0618:
	`Xamarin.Test.SomeObject.ObsoleteMethod()' is obsolete: `Deprecated please use IntegerMethod instead'

This warning was emitted for the "connector methods" which reference
the deprecated Java method.  Update
`CodeGenerator.WriteMethodCallback()` so that the connector-related
methods are *also* `[Obsolete]`, removing this warning.

With this change in place, we no longer need to allow warnings in our
CodeDom-based unit tests.
Latest commit 6ce89c7 Jan 10, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
Documentation Review, update, and flush docs. Apr 26, 2016
build-tools [jnienv-gen] missing TargetFrameworkVersion Dec 27, 2018
external Bump xamarin-android-tools to be in sync with XA Aug 27, 2018
lib Bump to mono.linq.expressions/e3372fbb (#70) Sep 1, 2016
samples/Hello [Java.Interop] Target .NET Standard 2.0 Dec 10, 2018
src [Android.Interop] Remove Android.Interop and related projects. (#411) Jan 8, 2019
tests [Java.Interop] Use right calling convention for JNI calls (#404) Dec 21, 2018
tools [generator] Remove CS0108 warning for inherited methods (#412) Jan 10, 2019
.gitattributes [build] Use .csproj files, not .mdproj files (#277) Mar 28, 2018
.gitignore Update .gitignore (#375) Sep 25, 2018
.gitmodules [Java.Interop.BootstrapTasks] Use JdkInfo (#349) Jul 27, 2018
Before.Java.Interop.sln.targets [tests] use wildcards for simpler generator integration tests (#290) Apr 11, 2018 [Java.Runtime.Environment] Use libjli.dylib on macOS, not libjvm.dylib ( Oct 25, 2017
Configuration.props [build] Remove warnings Oct 11, 2018
Java.Interop.sln [Android.Interop] Remove Android.Interop and related projects. (#411) Jan 8, 2019
LICENSE Add MIT/X11 License. Apr 26, 2016
Makefile [Android.Interop] Remove Android.Interop and related projects. (#411) Jan 8, 2019 [Android.Interop] Remove Android.Interop and related projects. (#411) Jan 8, 2019
gendarme-ignore.txt [java-interop] Require dynamic JVM loading (#338) Jun 27, 2018
product.snk [Java.Interop, Java.Interop.Dynamic, Java.Interop.Export] Sign assemb… May 10, 2016



Java.Interop is a binding of the Java Native Interface for use from managed languages such as C#, and an associated set of code generators to allow Java code to invoke managed code. It is also a brain-delusional Second System Syndrome rebuild of the monodroid/Xamarin.Android core, intended to fix some of the shortcomings and design mistakes I've made over the years.

In particular, it attempts to fix the following issues:

  • Split out the core invocation logic so that the containing assembly is in the xbuild-frameworks\MonoAndroid\v1.0 directory, allowing low-level JNI use without taking an API-level constraint.
  • Make the assembly a PCL lib.
  • Support use of the lib on "desktop" Java VMs. This would allow more testing without an Android device, could allow using Xamarin.Android Views to be shown in the GUI designer, etc.
  • Improve type safety.
  • Improve consistency.

In particular are the last two points: Xamarin.Android currently uses IntPtrs everywhere, and it's not at all obvious what they are (method IDs vs. local refs vs. global refs vs. ...). This culminates in JNIEnv.FindClass(), which returns a global reference while most other methods return a local ref.

The JNIEnv API is also huge, unwieldy, and terrible.

Build Requirements

Latest Mono from

Build Configuration

The Java.Interop build can be configured by overriding make(1) variables on the command line or by specifying MSBuild properties to control behavior.

make(1) variables

The following make(1) variables may be specified:

  • $(CONFIGURATION): The product configuration to build, and corresponds to the $(Configuration) MSBuild property when running $(MSBUILD). Valid values are Debug and Release. Default value is Debug.

  • $(RUNTIME): The managed runtime to use to execute utilities, tests. Default value is mono64 if present in $PATH, otherwise mono.

  • $(TESTS): Which unit tests to execute. Useful in conjunction with the make run-tests target:

      make run-tests TESTS=bin/Debug/Java.Interop.Dynamic-Tests.dll
  • $(V): If set to a non-empty string, adds /v:diag to $(MSBUILD_FLAGS) invocations.

  • $(MSBUILD): The MSBuild build tool to execute for builds. Default value is xbuild.

MSBuild Properties

MSbuild properties may be placed into the file Configuration.Override.props, which can be copied from The Configuration.Override.props file is <Import/>ed by Configuration.props; there is no need to <Import/> it within other project files.

Overridable MSBuild properties include:

  • $(CecilSourceDirectory): Directory for the cecil sources. Defaults to external/cecil.
  • $(JdkJvmPath): Full path name to the JVM native library to link java-interop against. By default this is probed for from numerous locations within build-tools/scripts/
  • $(JavaCPath): Path to the javac command-line tool, by default set to javac.
  • $(JarPath): Path to the jar command-line tool, by default set to jar.
    • It may be desirable to override these on Windows, depending on your PATH.
  • $(UtilityOutputFullPath): Directory to place various utilities such as class-parse, generator, and logcat-parse. This value should be a full path. By default this is $(MSBuildThisFileDirectory)bin/$(Configuration).

Type Safety

The start of the reboot was to use strongly typed SafeHandle subclasses everywhere instead of IntPtr. This allows a local reference to be type-checked and distinct from a global ref, complete with compiler type checking.

Since we now have actual types in more places, we can move the current JNIEnv methods into more semantically meaningful types.

Unfortunately, various tests demonstrated that while SafeHandles provided increased type safety, they did so at a large runtime cost:

  1. SafeHandles are reference types, increasing GC heap allocations and pressure.
  2. SafeHandles are thread-safe in order to prevent race conditions and handle recycling attacks.

Compared to a Xamarin.Android-like "use IntPtrs for everything" binding approach, the overhead is significant: to just invoke JNIEnv::CallObjectMethod(), using SafeHandles for everything causes execution time to take ~1.4x longer than a comparable struct-oriented approach.

Make the test more realistic -- compared to current Xamarin.Android and current Java.Interop -- so that JniEnvironment.Members.CallObjectMethod() also calls JniEnvironment.Errors.ExceptionOccurred(), which also returns a JNI local reference -- and runtime execution time jumped to ~3.6x:

# SafeHandle timing: 00:00:09.9393493
#	Average Invocation: 0.00099393493ms
# JniObjectReference timing: 00:00:02.7254572
#	Average Invocation: 0.00027254572ms

(See the tests/invocation-overhead directory for the invocation comparison sourcecode.)

This is not acceptable. Performance is a concern with Xamarin.Android; we can't be making it worse.

Meanwhile, I really dislike using IntPtrs everywhere, as it doesn't let you know what the value actually represents.

To solve this issue, avoid SafeHandle types in the public API.

Downside: this means we can't have the GC collect our garbage JNI references.

Upside: the Java.Interop effort will actually be usable.

Instead of using SafeHandle types, we introduce a JniObjectReference struct type. This represents a JNI Local, Global, or WeakGlobal object reference. The JniObjectReference struct also contains the reference type as JniObjectReferenceType. jmethodID and jfieldID become "normal" class types, permitting type safety, but lose their SafeHandle status, which was never really necessary because they don't require cleanup anyway. Furthermore, these values should be cached -- see JniPeerMembers -- so making them GC objects shouldn't be a long-term problem.

By doing so, we allow Java.Interop to have two separate implementations, controlled by build-time #defines:

  • FEATURE_HANDLES_ARE_SAFE_HANDLES: Causes JniObjectReference to contain a SafeHandle wrapping the underlying JNI handle.
  • FEATURE_HANDLES_ARE_INTPTRS: Causes JniObjectReference to contain an IntPtr for the underlying JNI handle.

The rationale for this is twofold:

  1. It allows swapping out "safer" SafeHandle and "less safe" IntPtr implementations, permitting easier performance comparisons.
  2. It allows migrating the existing code, as some of the existing tests may assume that JNI handles are garbage collected, which won't be the case when FEATURE_HANDLES_ARE_INTPTRS is set.

Naming Conventions

Types with a Java prefix are "high-level" types which participate in cross-VM object-reference semantics, e.g. you could add a JavaObject subclass to a Java-side collection, perform a GC, and the instance will survive the GC.

Types with a Jni prefix are "low-level" types and do not participate in object-reference semantics.


JDK and Global References

The JDK VM supports an effectively unlimited number of global references. While Dalvik bails out after creating ~64k GREFs, consider the following on the JDK:

var t = new JniType ("java/lang/Object");
var c = t.GetConstructor ("()V");
var o = t.NewInstance (c);
int count = 0;
while (true) {
    Console.WriteLine ("count: {0}", count++);
    o.NewGlobalRef ();

I halted the above loop after reaching 25686556 instances.

count: 25686556

I'm not sure when the JDK would stop handing out references, but it's probably bound to process heap limits (e.g. depends on 32-bit vs. 64-bit process).

Building on Windows

Building Java.Interop on Windows requires .NET and the msbuild command be available within the Command-Line environment. (The Developer Command Prompt that Visual Studio installs is sufficient.)

MSBuild version 15 or later is required.

  1. Install the build requirements.

  2. Clone the java.interop repo:

    git clone
  3. Navigate to the java.interop directory

  4. Prepare the project:

    msbuild Java.Interop.sln /t:Prepare

    This will ensure that the build dependencies are installed, perform git submodule update, download NuGet dependencies, and other "preparatory" and pre-build tasks that need to be performed.

  5. Build the project (or open and build with an IDE):

    msbuild Java.Interop.sln