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 IntPtr
s
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.
Latest Mono from http://www.mono-project.com/
The Java.Interop build can be configured by overriding make(1) variables on the command line or by specifying MSBuild properties to control behavior.
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 areDebug
andRelease
. Default value isDebug
. -
$(RUNTIME)
: The managed runtime to use to execute utilities, tests. Default value ismono64
if present in$PATH
, otherwisemono
. -
$(TESTS)
: Which unit tests to execute. Useful in conjunction with themake 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 isxbuild
.
MSbuild properties may be placed into the file Configuration.Override.props
,
which can be copied from
Configuration.Override.props.in
.
The Configuration.Override.props
file is <Import/>
ed by
Directory.Build.props
; there is no need to
<Import/>
it within other project files.
Overridable MSBuild properties include:
$(CecilSourceDirectory)
: If the empty string, Cecil will be obtained from NuGet packages. Otherwise,$(UtilityOutputFullPath)Xamarin.Android.Cecil.dll
will be used to reference Cecil.$(JdkJvmPath)
: Full path name to the JVM native library to linkjava-interop
against. By default this is probed for from numerous locations withinbuild-tools/scripts/jdk.mk
.$(JavaCPath)
: Path to thejavac
command-line tool, by default set tojavac
.$(JarPath)
: Path to thejar
command-line tool, by default set tojar
.- It may be desirable to override these on Windows, depending on your
PATH
.
- It may be desirable to override these on Windows, depending on your
$(UtilityOutputFullPath)
: Directory to place various utilities such asclass-parse
,generator
, andlogcat-parse
. This value should be a full path. By default this is$(MSBuildThisFileDirectory)bin/$(Configuration)
.
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 SafeHandle
s provided
increased type safety, they did so at a large runtime cost:
SafeHandle
s are reference types, increasing GC heap allocations and pressure.SafeHandle
s are thread-safe in order to prevent race conditions and handle recycling attacks.
Compared to a Xamarin.Android-like "use IntPtr
s for everything" binding
approach, the overhead is significant: to just invoke
JNIEnv::CallObjectMethod()
, using SafeHandle
s 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 IntPtr
s 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 #define
s:
FEATURE_HANDLES_ARE_SAFE_HANDLES
: CausesJniObjectReference
to contain aSafeHandle
wrapping the underlying JNI handle.FEATURE_HANDLES_ARE_INTPTRS
: CausesJniObjectReference
to contain anIntPtr
for the underlying JNI handle.
The rationale for this is twofold:
- It allows swapping out "safer"
SafeHandle
and "less safe"IntPtr
implementations, permitting easier performance comparisons. - 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.
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.
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
^C
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 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.
-
Install the build requirements.
-
Clone the java.interop repo:
git clone https://github.com/xamarin/java.interop.git
-
Navigate to the
java.interop
directory -
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. -
Build the project (or open and build with an IDE):
msbuild Java.Interop.sln