Java library binding with JavaDocs for Xamarin.Android

Java library binding with JavaDocs for Xamarin.Android

Short introduction

Xamarin platform enables Android application development. Developer has option to create application with either Xamarin.Forms approach or Xamarin.Android. Besides which way you choose sometimes there is a need to use native libraries which are written in Java. There are many open source projects available on GitHub connected, especially connected with custom controls. Of course developer can rewrite them to C# but why? There is a another great solution to access them from Xamarin.Android.

This solution is called “Library binding” and enables binding between Java and C#. Developer does not have to rewrite the whole library code then. In this article I would like to present how to do such binding.

What do I need to start?

1) Visual Studio 2017 Community (for free or choose higher version) or Visual Studio for MAC

2) Android Studio

Let’s start

First of all we need to find native Android project on GitHub. I decided to create binding library for John Persano SuperToasts Library.


Download project from GitHub and open it in Android Studio

Once you download the project from GitHub, open it in Android Studio. Make sure that you have API’s and Build Tools actual. Project structure should look like below:


Change build variant to “release”

Before we build project, make sure that build variant is set to “release” like presented below:


Rebuild project

Once project is built we can check “outputs” folder and look for “.aar” file:

Once we have Android Archive Library ready we can now generate JavaDocs documentation for it.


Generate JavaDocs

In Android Studio select “Tools” and click “Generate JavaDoc…”:

From opened window select “Module library”:

Specify “Output directory” and click “OK” button. JavaDocs files should be generated in specified folder:

Done! Now we are ready to create Xamarin.Android Binding Library.


Open Visual Studio and create Binding Library project

Once you open Visual Studio click “File” then “New project” and select “Bindings library” in Android section:

Type name of your the project and select path:

Once project is created it has structure like below:

You can see that there is folder called “Jars”. This is the place where we can place “.jar” and “.aar” files to be wrapped in bindings library.

Right click on “Jars” folder and select “Add files”. Choose “.aar” file we generated in Android Studio:

Now folder should containd “.aar” file:

We need to also check if “.aar” file has proper build action.

For “.aar” file it should be “LibraryProjectZip” and for “.jar” file it should be “EmbeddedJar”:

You can read more about build action types here.


Add JavaDocs to Binding Library

Now we want to add java doc so we can read documentation for code.

Create new folder called “JavaDocs”:

Now right click and this folder and select “Reveal in folder”. Copy all files from previous folder where we generated JavaDocs in Android Studio. Paste them in this folder.

Now in Visual Studio right click on the “JavaDocs” folder, select “Add” and then “Add files”. From the folder select only file with name “Index.html”:

Once you add “index.html” file make sure that it has proper “Build action”. It should be set to “JavaDocIndex”:

Rebuild project:

As you can see there are some errors. It is because sometimes Java Binding Library do not now how to translate some code from Java to C#.

That is why Xamarin provides options to customize binding settings. You can read more about it here.

To fix problems open “Transformations” folder and then open “Metadata.xml” file:

Now edit file to look like below:

<?xml version="1.0" encoding="UTF-8"?>
<attr path="/api/package[@name='com.github.johnpersano.supertoasts.library']/class[@name='SuperActivityToast']/method[@name='getDismissTag']" name="visibility">protected</attr>
<attr path="/api/package[@name='com.github.johnpersano.supertoasts.library']/class[@name='SuperActivityToast']/method[@name='getDismissToken']" name="visibility">protected</attr>

What we did here is a small change connected with access modifier for “getDismissTag” and “getDismissToken” in C#. By default Binding Library mechanism is trying to set “public” modifier on these methods but they are protected in Java native code. This is how we can solve this problem.


Rebuild project and check generated files

Once you rebuild project, open “Bin/Debug” folder. There should be “.dll” file generated:

Create sample Xamarin.Android application project and add reference to generated binding library

Once we have our library generated we can test it in sample application.

Right click on “References” and select “and add generated library:


Now in “MainActivity.cs” add below fragment of code in “OnCreate” method:

SuperActivityToast.Create(this, new Style(), Style.TypeButton)
.SetText("Hello Super Toast!")

Add proper using so “SuperActivityToast” class is visible.

Now we can check if JavaDocs are correctly generated. Move mouse cursor on “SetButtonText” method and see summary:


Sum up

Launch the application and see result:

I hope that this article will help you to bind some great native libraries for Xamarin.Android apps. Of course you can use it with Xamarin.Froms apps too. Good luck!