Building IoTivity with Java Bindings

A tool called SWIG is used to generate Java language bindings for IoTivity. SWIG is an interface compiler that connects programs written in C and C++ with other languages such as Java.

SWIG is not a stub generator. It produces code that can be compiled and used. The output is generated by a tool. For this reason there is little or no encapsulation of the code to make it appear more like what most Java developers would expect. The output with very few exceptions are just a collection of classes filled with static methods. This has both the advantage and disadvantage that the way the code is used in Java is similar to the way it is used in C. This means the code does not resemble what a typical Java programmer expects but it is easy for someone familiar with the C code to follow the flow of the code.

Since the Java binding is just a thin layer on top of IoTivity’s C APIs, any programs developed using Java are expected to be as stable as the underlying C stack.

To use this code you will need the following:

git version control system
SWIG installed on your local system (version 3.0 recommended)
Java Development kit.

The SWIG output should work with Java 6 and newer. The output has been tested against OpenJDK 1.8. Due to licensing changes the output is no longer tested against Oracle Java.

Currently SWIG version 3.0 is recommended. Users are welcome to use a newer version so long as they are aware it has not been as extensively tested.

Linux Build instructions

Install the build tools git, swig, Java Development kit, make, and C compiler

sudo apt-get install git swig build-essential openjdk-8-jdk make

Build Java language bindings Navigate to <iotivity-root>/port/linux

make IPV4=1 DEBUG=1 JAVA=1 IDD=1

Building and Running Samples A sample server and client can be found in <iotivity-root>/swig/apps/<sample>

The server sample is in java_lite_simple_server. To build and run the sample execute the following commands.

./build-simple-server-lite.sh
./run-simple-server-lite.sh

The client sample is in java_lite_simple_client. To build and run the sample execute the following commands.

./build-simple-client-lite.sh
./run-simple-client-lite.sh

The Onboarding tool sample is in java_onboarding_tool. To build and run the onboarding tool execute the following commands.

./build-onboarding-tool-lite.sh
./run-onboarding-tool-lite.sh

Windows Build Instructions

Install the build tools

Git
SWIG
Java Development Kit (JDK) AdoptOpenJDK or Oracle Java 8 JDK
Visual Studio

Visual Studio 2015 was used for Windows development with IoTivity. The Visual Studio solution files will work with newer versions of Visual Studio.

Set the JAVA_HOME environment variable to point to the Java Development kit. This is required so the build can locate jni.h.

Build Java language bindings

To build the IoTivity JNI shared library, navigate to <iotivity-root>/port/windows/vs2015 and open the Visual Studio solution IoTivity-lite-Java.sln file in Visual Studio.

Select the desired build options: Release/Debug, x86/x64. Note that the architecture must match that of the Java VM installed on the system. In the Solution Explorer right click on the iotivity-lite-jni project. Select the Build option.

This will build -IoTivity-lite.lib -swig generated wrapper code -iotivity-lite-jni.dll

On success, the Output window shows the following:

========== Build: 3 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Build iotivity-lite.jar file from <iotivity-root>/swig/java_lang run:

sh build-iotivity-lite.sh

The Java build has not been integrated with the Visual Studio solution. Hence, we must run the build-iotivity-lite.sh script following the execution of build on Visual Studio.

Building and Running Samples

A sample server and client can be found in <iotivity-root>/swig/apps/<sample>.

The server sample is java_lite_simple_server. To build and run the sample execute the following commands:

sh build-simple-server-lite.sh
run-simple-server-lite.cmd

The client sample is in java_lite_simple_client. To build and run the sample execute the following commands:

sh build-simple-client-lite.sh
run-simple-client-lite.cmd

The Onboarding tool sample is in java_onboarding_tool. To build and run the onboarding tool execute the following commands:

sh build-onboarding-tool-lite.sh
run-onboarding-tool-lite.cmd

Windows build issues

The Visual Studio build does properly catch changes in the swig interface files, (i.e. *.i and *.swg files found in the swig/swig_interfaces directory) if any of these are updated. The Rebuild option must be used to build the output or the swig output will not be updated or sh build_swig.sh may be run from the <iotivity-root>/swig/java_lang directory and then run Build.

Visual Studio does not clean the *.java output files even on a clean or rebuild. The files may be manually deleted from the <iotivity-root>/swig/iotivity-lite-java/src/org directory or sh build_swig.sh can be run from the <iotivity-root>/swig/java_lang directory.

swig directory layout

This provides is an overview of the /swig directory with a summary of the contents of each sub-directory.

	swig
	|    +-- apps
	|    |    +-- android_simple_client
	|    |    +-- android_simple_server
	|    |    +-- java_lite_simple_client
	|    |    |    +-- src
	|    |    +-- java_lite_simple_server
	|    |    |    +-- src
	|    |    +-- oc
	|    +-- iotivity-lite-java
	|    |    +-- junit
	|    |    +-- src
	|    +-- java_lang
	|    +-- oc_java
	|    |    +-- oc
	|    +-- swig_interfaces
	- apps

Contains multiple samples. The java_lite samples have been tested on Windows and Linux. The android samples are the same samples with a really light UI for Android OS. The java_onboarding_tool is a bear bones tool for onboarding and provisioning samples that have been built with security.

The oc directory contains a collection of samples that take advantage of the org.iotivity.oc package which is an API layer built on top of the output generated by swig that gives the code a more object-oriented feel and usage.

iotivity-lite-java Contains unit test code in the junit directory as well as an empty src directory. The src directory will be populated with *.java classes when the SWIG build commands are run.
java_lang Contains build scripts that may be used to generate the Java language binding using SWIG. Most of the scripts have been incorporated into make or the Visual Studio build and no longer need to be called.
oc_java Contains Java files that are used by the SWIG output but not generated as part of the SWIG build process. Most of the files are Java interfaces used to handle callbacks and bitmask values.

The oc directory provides an object-oriented API layer above the SWIG generated bindings.

swig_interfaces Contains the input files for the swig builder. These files contain instructions for the SWIG builder. They tell swig which header files are being processed. It instructs swig how to rename files from a C style name with underscores to a Java like lower camel case name. It also instructs swig on how to work with data types that it does not understand by default such as oc_string_t. It also contains code that works around the fact that Java does not have a preprocessor so must handle many of the C macros differently.

Verify installation of needed tools

If issues are encountered when trying to build the code, you may verify the versions of the installed tools. The scripts assume that all the needed tools are in the system PATH and are accessible without knowing the location of the tool.

bash shell (windows only) this should be installed with git

sh --version

example of expected output

GNU bash, version 4.4.12(2)-release (x86_64-pc-msys)
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>

git

git --version

example of expected output (newest version recommended)

git version 2.20.1

SWIG

swig -version

example of expected output (version 3.0 currently recommended)

SWIG Version 3.0.12
Compiled with g++ [x86_64-redhat-linux-gnu]
Configured options: +pcre
Please see http://www.swig.org for reporting bugs and further information

Java

java -version

example of expected output

openjdk version "1.8.0_191"
OpenJDK RuntimeEnvironment (build 1.8.0_191-b12)
OprnJDK 64-bit Server VM (build 25.191-b12, mixed mode)

javac 1.8.0_191

Check JAVA_HOME environment variable

on windows

echo %JAVA_HOME%

example of expected output

C:\Program Files\AdoptOpenJDK\jdk-8.0.202.08

on Linux

echo $JAVA_HOME

example of expected output

/usr/lib/jvm/java-1.8.0/