README.md 13.5 KB
Newer Older
Larry Sachs's avatar
Larry Sachs committed
1
Java Language binding for IoTivity-Lite using SWIG
2
=================================================
George Nash's avatar
George Nash committed
3 4

Introduction
5
-------------------------------------------------
Larry Sachs's avatar
Larry Sachs committed
6
A tool called SWIG is used to generate Java language bindings for IoTivity-Lite.  SWIG is an
George Nash's avatar
George Nash committed
7
interface compiler that connects programs written in C and C++ with other languages such as Java.
8 9

SWIG is not a stubs generator.  It produces code that can be compiled and used.  The output is
George Nash's avatar
George Nash committed
10
generated by a tool.  For this reason there is little or no encapsulation of the code to make it
Larry Sachs's avatar
Larry Sachs committed
11 12 13 14 15
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.
16

17 18
Since the Java output is just a thin layer on top of IoTivity-lite C code any programs developed
using Java are expected to be as stable as the underlying C code.
George Nash's avatar
George Nash committed
19 20

Getting Started
21
-------------------------------------------------
George Nash's avatar
George Nash committed
22
To use this code you will need the following:
Larry Sachs's avatar
Larry Sachs committed
23
  - git version control system
24 25
  - A local copy of IoTivity-lite
  - SWIG installed on your local system (version 3.0 recommended)
George Nash's avatar
George Nash committed
26
  - Java Development kit.
George Nash's avatar
George Nash committed
27
  - C build tool for your desired system
George Nash's avatar
George Nash committed
28

29 30 31 32 33
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.  SWIG version 4.0 came out during the  development of the
Java language bindings.  Users are welcome to use a newer version as long as they are aware it has
34
not been as extensively tested.
George Nash's avatar
George Nash committed
35

36 37 38
Instructions for Android
-------------------------------------------------
Instructions for Android can be found <iotivity-lite>/port/android/README.md
George Nash's avatar
George Nash committed
39

40 41 42 43 44 45 46 47
Instructions for Linux
-------------------------------------------------
### Install build tools
- git, swig, Java Development kit, make, and C compiler

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

- A local copy of IoTivity-lite
George Nash's avatar
George Nash committed
48

Larry Sachs's avatar
Larry Sachs committed
49
Checkout IoTivity-Lite git project run the following command to get a anonymous copy of
50
iotivity-lite.
George Nash's avatar
George Nash committed
51

52
    git clone https://gitlab.iotivity.org/iotivity/iotivity-lite.git
George Nash's avatar
George Nash committed
53

Larry Sachs's avatar
Larry Sachs committed
54 55 56 57
If you are behind a proxy setup the git proxy settings before running the above commands

    git config --global http.proxy http://<username>:<password>@<proxy-server-url>:<port>

58
Since this is an anonymous download you will not be able to push any changes up to the project.
59 60
If you are planning on contributing back to IoTivity you will need to make a gitlab account and
request developer access to the iotivity-lite project.
61

62 63
### Build Java language bindings
Navigate to `<iotivity-lite>/port/linux`
George Nash's avatar
George Nash committed
64

65
    make IPV4=1 DEBUG=1 JAVA=1 IDD=1
George Nash's avatar
George Nash committed
66

67
If make fails check see the Verify installation of needed tools section.
George Nash's avatar
George Nash committed
68

69 70
### Building and Running Samples
A sample server and client can be found in `<iotivity-lite>/swig/apps/<sample>`
George Nash's avatar
George Nash committed
71

72 73
The server sample is in `java_lite_simple_server`.  To build and run the sample execute the
following commands.
George Nash's avatar
George Nash committed
74

75 76
    ./build-simple-server-lite.sh
    ./run-simple-server-lite.sh
George Nash's avatar
George Nash committed
77

78 79
The client sample is in `java_lite_simple_client`.  To build and run the sample execute the
following commands.
George Nash's avatar
George Nash committed
80

81 82
    ./build-simple-client-lite.sh
    ./run-simple-client-lite.sh
George Nash's avatar
George Nash committed
83

84 85
The Onboarding tool sample is in `java_onboarding_tool`. To build and run the onboarding tool
execute the following commands.
George Nash's avatar
George Nash committed
86

87 88
    ./build-onboarding-tool-lite.sh
    ./run-onboarding-tool-lite.sh
George Nash's avatar
George Nash committed
89 90


91 92
See the Simple Step-by-Step guide for onboarding and provisioning section found in the root level
README for step-by-step instructions to onboard and test the samples.
George Nash's avatar
George Nash committed
93

94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
Instructions for Windows
-------------------------------------------------
### Install build tools
 - Git can be obtained for Windows [here](https://git-scm.com/download/win).
 - SWIG can be downloaded [here](http://swig.org/download.html).
 - Java Development Kit (JDK) choose one (AdoptOpenJDK recommended)<br />
   AdoptOpenJDK can be [downloaded here](https://adoptopenjdk.net/installation.html)<br />
   Oracle Java 8 JDK can be
   [downloaded here](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
 - Download Visual Studio [here](https://visualstudio.microsoft.com/).

   For development on Windows Visual Studio 2015 was used.  The Visual Studio solution files have
   been tested in newer versions of Visual Studio and have been found to work.  Visual studio IDE
   Community edition and Visual Studio Code should work but have not personally been tested.

109 110
Set JAVA_HOME environment variable to point to the Java Development kit. This is required so the
build can find the jni.h header files.
111

112
### Build Java language bindings
George Nash's avatar
George Nash committed
113
Build the JNI shared library:
114

George Nash's avatar
George Nash committed
115
Navigate to `<iotivity-lite>/port/windows/vs2015` open the Visual Studio solution
116
`IoTivity-lite-Java.sln` file in Visual Studio.
117

George Nash's avatar
George Nash committed
118
Select the desired build options: Release/Debug, x86/x64.  Note the x86/x64 must match the
119
architecture of the Java VM installed on the system.  In the Solution Explorer right click
120
on the `iotivity-lite-jni` project.  Select the `Build` option.
121

George Nash's avatar
George Nash committed
122
This will build
123
  - `IoTivity-lite.lib`
124
  - swig generated wraper code
George Nash's avatar
George Nash committed
125 126 127 128
  - `iotivity-lite-jni.dll`

On success the Output window should show:

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

131
Build `iotivity-lite.jar` file from `<iotivity-lite>/swig/java_lang` run:
George Nash's avatar
George Nash committed
132 133

    sh build-iotivity-lite.sh
George Nash's avatar
George Nash committed
134

135 136
The Java build has not been integrated with Visual Studio. Running build-iotivity-lite.sh script is
a required extra step in addition to the Visual Studio build.
Larry Sachs's avatar
Larry Sachs committed
137

138 139
If the `iotivity-lite-java` project is imported into Eclipse then the Eclipse IDE can be used to
build `iotivity-lite.jar` instead of the shell script. See "Eclipse project files" section below.
George Nash's avatar
George Nash committed
140

141
If the build fails see the "Verify installation of needed tools" section.
George Nash's avatar
George Nash committed
142

143
### Building and Running Samples
144 145
A sample server and client can be found in `<iotivity-lite>/swig/apps/<sample>`

George Nash's avatar
George Nash committed
146 147
The server sample is in `java_lite_simple_server`.  To build and run the sample execute the
following commands.
148

George Nash's avatar
George Nash committed
149 150
    sh build-simple-server-lite.sh
    run-simple-server-lite.cmd
151

George Nash's avatar
George Nash committed
152 153
The client sample is in `java_lite_simple_client`.  To build and run the sample execute the
following commands.
154

George Nash's avatar
George Nash committed
155 156
    sh build-simple-client-lite.sh
    run-simple-client-lite.cmd
George Nash's avatar
George Nash committed
157

158 159
The Onboarding tool sample is in `java_onboarding_tool`. To build and run the onboarding tool
execute the following commands.
Larry Sachs's avatar
Larry Sachs committed
160

161 162
    sh build-onboarding-tool-lite.sh
    run-onboarding-tool-lite.cmd
George Nash's avatar
George Nash committed
163

164 165
See the Simple Step-by-Step guide for onboarding and provisioning section found in the root level
README for step-by-step instructions to onboard and test the samples.
George Nash's avatar
George Nash committed
166

167 168 169 170 171 172
### Windows specific build issues
Visual Studio does not know how to properly rebuild when the swig interface files have been change
(i.e. *.i and *.swg files found in the swig_interfaces directory) if any of these files 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` can be run from the ``<iotivity-lite>/swig/java_lang` directory and then run
**Build**.
George Nash's avatar
George Nash committed
173

174 175 176
Visual Studio does not clean the *.java output files even on a clean or rebuild.  The files may
manually be deleted from the `<iotivity-lite>/swig/iotivity-lite-java/src/org` directory or
`sh build_swig.sh` can be run from the ``<iotivity-lite>/swig/java_lang` directory.
George Nash's avatar
George Nash committed
177

178 179
Layout of swig directory
-------------------------------------------------
180 181
This contains an overview of the contents of the `<iotivity-lite>/swig` directory.  With a
summary of the contents of each directory.
George Nash's avatar
George Nash committed
182 183 184 185 186 187 188 189 190

    swig
    +-- apps
    |   +-- android_simple_client
    |   +-- android_simple_server
    |   +-- java_lite_simple_client
    |   |   +-- src
    |   +-- java_lite_simple_server
    |   |   +-- src
191
    |   +-- oc
Larry Sachs's avatar
Larry Sachs committed
192
    +-- iotivity-lite-java
George Nash's avatar
George Nash committed
193 194 195 196
    |   +-- junit
    |   +-- src
    +-- java_lang
    +-- oc_java
197
    |   +-- oc
George Nash's avatar
George Nash committed
198 199
    +-- swig_interfaces

George Nash's avatar
George Nash committed
200
- `apps`<br />
201 202 203 204 205 206 207 208 209
  Contains multiple samples.  The `java_lite` samples have been run and tested on Windows and Linux.
  The `android` samples are the same samples with a really light UI for Android OS. The `java_lite`
  samples also contain project files for the Eclipse IDE if users wish to import the samples into
  that IDE. The `java_onboarding_tool` is a bear bones tool for onboarding and provisioning samples
  that have been built with security.

  The `oc` directory is a collection of samples that take advantage of the org.iotivity.oc package
  which is a layer built on top of the output generated by swig that gives the code a more object
  oriented feel and usage.
Larry Sachs's avatar
Larry Sachs committed
210
- `iotivity-lite-java`<br />
211 212 213 214
  Contains unit test code in the `junit` directory as well as an empty `src` directory.  The
  `src` directory will be populated with `*.java` files when the SWIG build commands are run.
  This also contains project files for the Eclipse IDE if user wishes to import the
  iotivity-lite code into Eclipse.
George Nash's avatar
George Nash committed
215
- `java_lang`<br />
216 217
  Contains build scripts that may be used to generate the Java language binding using SWIG.  Most of
  the scripts have been incorporated with make or Visual Studio and no longer need to be called.
George Nash's avatar
George Nash committed
218
- `oc_java`<br />
219 220 221
  Contains Java files that are used by the SWIG output but not not generated as part of the SWIG
  build process.  Most of the files are Java interfaces used to handle callbacks and bitmask
  values.
222 223 224

  The `oc` directory contains a layer ontop of the swig generated output that is more object oriented
  than the output from swig.
George Nash's avatar
George Nash committed
225
- `swig_interfaces`<br />
226
  Contains the input files for the swig builder.  These files contain instructions for the SWIG
227
  builder.  They tell swig which header files are being processed.  It instructs swig how to rename
228 229 230 231
  files from a C style name with underscores to a Java like lower camel case name.  It also
  instructs swig how to work with data types that it does not understand by default.  Data types
  like `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.
George Nash's avatar
George Nash committed
232 233

Eclipse project files
234
-------------------------------------------------
235 236
Where possible command line build scripts have been provided for building and running the code.
However much of the development was done using the Eclipse IDE.  The project files have been
George Nash's avatar
George Nash committed
237
committed so other developers can take advantage of the Eclipse IDE if they wish.
George Nash's avatar
George Nash committed
238 239 240 241

To open the project files:
 - Open Eclipse
 - select `File->Import..`
242
 - select `General->Existing Projects into Workspace`
George Nash's avatar
George Nash committed
243 244 245
 - click `Next>` button
 - click the `Browse..` button next to the `Select root directory:` text box
 - browse to the `<iotivity-lite>\swig` directory click `OK`
George Nash's avatar
George Nash committed
246
 - make sure the checkbox for the desired projects is checked.  Click `Finish`
George Nash's avatar
George Nash committed
247

248 249
Run the unit tests by right clicking on `iotivity-lite` project select `Run As -> JUnit Test`.
Selecting `Run As -> Java Application` will run the command line version of the unit tests.
George Nash's avatar
George Nash committed
250 251 252 253

Run samples by right clicking on the sample select
`Run As -> Java Application`.

254 255 256 257
If the code was previously built using the command-line build scripts you may get build warnings
indicating some class files can not be found.  Select `Project -> Clean...`.  Then right click on
the `iotivity-lite` project and select `Refresh`.  This should force the project to rebuild the
all the class files associated with the `iotivity-lite.jar` file.
258

259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313
Verify installation of needed tools
-------------------------------------------------
If issues are encountered when trying to build the code verify the tools can be found. The scripts
assume all the needed tools are on PATH and are accessible without knowing the location of the tool.

Run the following to verify each tool.  At this time there are no known issues limiting users to
the same version of the tools as were used for development.  Feel free to use the latest version of
all the development tools.

---
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
    javac -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

314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333
---

Check JAVA_HOME environment variable
(Windows)

    echo %JAVA_HOME%

example of expected output

    C:\Program Files\AdoptOpenJDK\jdk-8.0.202.08

(Linux)

    echo $JAVA_HOME

example of expected output

    /usr/lib/jvm/java-1.8.0/

---
334
If any tools are not found make sure the location of the tool is added to the system PATH.
Larry Sachs's avatar
Larry Sachs committed
335

336 337
If JAVA_HOME is not found add it to your environment variables.

George Nash's avatar
George Nash committed
338
Send Feedback
339
-------------------------------------------------
Larry Sachs's avatar
Larry Sachs committed
340
Questions
341
[IoTivity-Lite Developer Mailing List](https://iotivity.groups.io/g/iotivity-dev)
Larry Sachs's avatar
Larry Sachs committed
342 343

Bugs
344
[IoTivity-lite gitlab issues](https://gitlab.iotivity.org/iotivity/iotivity-lite/issues)