Introduction

A not so long time ago, JNI layer and Java classes for liblinphone were wrapped manually. When a new function was added into liblinphone, we had to manually wrap it in Java/JNI which was costly, and because it was manual, sometimes the naming wasn't consistent, and some functions recently added in C library were not available in java.

Now, like the C++, C# and Python wrappers, it will be automatically generated, which provides many advantages:

  • When a feature is added into liblinphone, it is directly available in Java at no extra cost ;
  • The naming between Java and C code is consistent, so it's easy to find the native method the Java/JNI code calls ;
  • It prevents a lot of coding mistakes in the JNI layer.

The only downside is the migration cost between the previous Java wrapper and the new one.

To ease this process, we provide a sed script that does most of the work, but there are still some manual changes required because some of the methods you could have used no longer exist or take different parameters or return a different type of value... Also some methods were throwing exceptions and aren't anymore, or now throw exceptions when they weren't.

Everything in the org.linphone.core package is automatically generated except for the org.linphone.core.tools package which contain classes that are manually written in liblinphone and copied into the generated Java classes after the generation. Theses classes are either tools for developpers (H264Helper) or mandatory code that liblinphone will call using JNI (AndroidPlatformHelper).

Compiling the new Java wrapper

The new wrapper is now the default setting for linphone-android, so if you are up-to-date you are most certainly building and using it.

It is possible to disable it using the prepare.py script's -DENABLE_JAVA_WRAPPER=NO option.

The JNI file will be automatically generated and added to linphone's build, and the Java classes will be generated in the liblinphone-sdk/<arch>/share/linphonej/java/ directory.

New java wrapper class reference documentation

The reference documentation (classes, method etc...) is available here:

https://www.linphone.org/snapshots/docs/liblinphone/multilang/reference/java/index.html

Migrating to the new Java wrapper

Because the Java files are no longer stored in the linphone submodule, you need to edit first your build.gradle file with the following changes:

def submoduleDir = ['submodules/mediastreamer2/java/src',
'submodules/linphone/java/j2se',
'submodules/linphone/java/common',
'submodules/linphone/java/impl',
'submodules/linphone/coreapi/help/examples/java']

becomes

def submoduleDir = ['submodules/mediastreamer2/java/src']

and

srcDirs.addAll(['src/android'])

is now

if (file('liblinphone-sdk/android-arm64/share/linphonej/java/org/linphone/core/Factory.java').exists() )
    rootSdk = 'liblinphone-sdk/android-arm64'
else if (file('liblinphone-sdk/android-arm/share/linphonej/java/org/linphone/core/Factory.java').exists() )
    rootSdk = 'liblinphone-sdk/android-arm'
else if (file('liblinphone-sdk/android-armv7/share/linphonej/java/org/linphone/core/Factory.java').exists() )
    rootSdk = 'liblinphone-sdk/android-armv7'
else if (file('liblinphone-sdk/android-x86/share/linphonej/java/org/linphone/core/Factory.java').exists() )
    rootSdk = 'liblinphone-sdk/android-x86'
else {
        println ("native sdk not ready yet")
        rootSdk = ""
}

srcDirs.addAll([rootSdk+'/share/linphonej/java/org/linphone/core/','src/android'])

There is a sed script named migration.sh that will do most of the work and it is located in wrappers/java/ directory of linphone project. Just run it to update your android application code:

./submodules/linphone/wrappers/java/migration.sh

It will take some time for the script to find and replace what can be automatically done.

Once it has finished, there will be issues in Android Studio. At the bottom of the sed script there is a list of known issues and how to resolve them.

Because we are at the same time making big changes in linphone C code, it is likely the generated code will differ a bit and thus create some more migration issues not handled nor documented in the sed script, but it shouldn't be hard to fix.

What to do if I cannot migrate.

It is still possible to use the former java wrapper by using the linphone-android branch 3.4.x . However, this branch will be deprecated, so we highly recommend to migrate to the new wrapper.

 

Tags:
Created by Sylvain Berfini on 2017/11/06 13:04