Java binding implementation and tests.

Author: andrew-buckley

.gitignore

@@ -187,6 +187,10 @@ c/common/tools/macro_utils_h_generator/macro_utils_h_generator.exe
 **/java/**/*.iml
 **/java/**/*dependency-reduced-pom.xml
 tools/jenkins-cli.jar
+*.class
+*.jar
+**/target/
+*.iml
 
 # Node.js
 **/.settings/
@@ -199,7 +203,7 @@ typings/**
 
 # ignore cmake build folder
 .cmake/**
-build/**
+*build/**
 
 # ignore Atom Editor files
 .atom-build.json

CMakeLists.txt

@@ -1,9 +1,14 @@
+#Copyright (c) Microsoft. All rights reserved.
+#Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+#this is CMakeLists.txt for root
 cmake_minimum_required(VERSION 2.8.11)
 project(azure_iot_gateway_sdk)
 
 #the following variables are project-wide and can be used with cmake-gui
 option(run_e2e_tests "set run_e2e_tests to ON to run e2e tests (default is OFF) [if possible, they are always build]" OFF)
 option(install_executables "should cmake run cmake's install function (that includes dynamic link libraries) [it does for yocto]" OFF)
+option(enable_java_binding "set enable_java_binding to ON to enable building of Java binding (default is OFF)" OFF)
 
 option(run_as_a_service "Flags that we have the goal of running gateway as a service for samples and OS that supports it." OFF)
 
@@ -99,4 +104,6 @@ include_directories(${GW_INC})
 
 add_subdirectory(modules)
 
-add_subdirectory(samples)
+add_subdirectory(samples)
+
+add_subdirectory(bindings)

bindings/CMakeLists.txt

@@ -0,0 +1,9 @@
+#Copyright (c) Microsoft. All rights reserved.
+#Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+cmake_minimum_required(VERSION 2.8.11)
+#this is CMakeLists for the bindings
+
+if(${enable_java_binding})
+    add_subdirectory(java)
+endif()

bindings/java/CMakeLists.txt

@@ -0,0 +1,122 @@
+#Copyright (c) Microsoft. All rights reserved.
+#Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+cmake_minimum_required(VERSION 2.8.11)
+#this is CMakeLists for java binding
+
+# Check if the environment variables NODE_INCLUDE and NODE_LIB exist
+if(
+    (NOT (DEFINED ENV{JAVA_HOME}))
+  )
+  message(FATAL_ERROR "Environment variable JAVA_HOME is not defined. Please define "
+                      "JAVA_HOME to point to the location of the JDK.")
+endif()
+
+set(java_module_host_manager_sources
+    ./src/java_module_host_manager.c
+)
+
+set(java_module_host_manager_headers
+    ./inc/java_module_host_manager.h
+)
+
+set(java_module_host_sources
+	./src/java_module_host.c
+    ${java_module_host_manager_sources}
+)
+
+set(java_module_host_headers
+    ./inc/message_bus_proxy.h
+    ./inc/java_module_host_common.h
+    ./inc/java_module_host.h
+    ${java_module_host_manager_headers}
+)
+
+set(java_module_host_static_sources
+    ${java_module_host_sources}
+)
+
+set(java_module_host_static_headers
+    ${java_module_host_headers}
+)
+
+set(java_module_host_hl_sources
+    ./src/java_module_host_hl.c
+)
+
+set(java_module_host_hl_headers
+    ./inc/message_bus_proxy.h
+    ./inc/java_module_host_hl.h
+)
+
+set(java_module_host_hl_static_sources
+    ${java_module_host_hl_sources}
+)
+
+set(java_module_host_hl_static_headers
+    ${java_module_host_hl_headers}
+)
+
+if(WIN32)
+    set(java_include_dirs
+        $ENV{JAVA_HOME}/include 
+        $ENV{JAVA_HOME}/include/win32
+    )
+    set(java_link_dirs
+        $ENV{JAVA_HOME}/lib
+        $ENV{JAVA_HOME}/jre/bin/server
+    )
+    set(java_libs
+        $ENV{JAVA_HOME}/lib/jvm.lib
+    )
+elseif(LINUX)
+    set(java_include_dirs
+        $ENV{JAVA_HOME}/include 
+        $ENV{JAVA_HOME}/include/linux
+    )
+    set(java_link_dirs
+        $ENV{JAVA_HOME}/jre/lib/amd64/server
+    )
+    set(java_libs
+        $ENV{JAVA_HOME}/jre/lib/amd64/server/libjvm.so
+    )
+endif()
+
+set(LIBS ${java_libs} gateway)
+
+include_directories(./inc ${IOTHUB_CLIENT_INC_FOLDER})
+include_directories(${GW_INC})
+include_directories(${java_include_dirs})
+link_directories(${java_link_dirs})
+
+#this builds the java_module_host dynamic library
+add_library(java_module_host MODULE ${java_module_host_headers} ${java_module_host_sources})
+target_link_libraries(java_module_host ${LIBS})
+
+#this build the java_module_host static library
+add_library(java_module_host_static ${java_module_host_static_headers} ${java_module_host_static_sources})
+target_compile_definitions(java_module_host_static PRIVATE BUILD_MODULE_TYPE_STATIC)
+target_link_libraries(java_module_host_static ${LIBS})
+
+#this builds the java_module_host_hl dynamic library (by default it uses java_module_host linked statically)
+add_library(java_module_host_hl MODULE ${java_module_host_hl_headers} ${java_module_host_hl_sources})
+target_link_libraries(java_module_host_hl java_module_host_static ${LIBS})
+
+#this builds the java_module_host_hl static library (by default it uses the java_module_host linked statically)
+add_library(java_module_host_hl_static ${java_module_host_hl_static_headers} ${java_module_host_hl_static_sources})
+target_compile_definitions(java_module_host_hl_static PRIVATE BUILD_MODULE_TYPE_STATIC)
+target_link_libraries(java_module_host_hl_static java_module_host_static ${LIBS})
+
+linkSharedUtil(java_module_host)
+linkSharedUtil(java_module_host_static)
+linkSharedUtil(java_module_host_hl)
+linkSharedUtil(java_module_host_hl_static)
+
+add_module_to_solution(java_module_host)
+
+add_subdirectory(tests)
+
+if(install_executables)
+    install(TARGETS java_module_host LIBRARY DESTINATION lib)
+    install(TARGETS java_module_host_hl LIBRARY DESTINATION lib)
+endif()

bindings/java/README.md

@@ -0,0 +1,9 @@
+#Java Binding
+
+This document provides everything one might need to use and understand the Java Binding mechanism used by the **Microsoft Azure IoT Gateway SDK**.
+
+##Contents
+
+1. [**Dev box setup** - steps necessary to build modules in Java and run samples](../../doc/java_devbox_setup.md)
+2. [**High Level Design** - detailed description of the Java binding mechanism](devdoc/java_binding_hld.md)
+3. [**How-To Guide** - guide on how to write your own Java modules](../../doc/java_how_to.md)

bindings/java/devdoc/Design.png

@@ -11,7 +11,7 @@ JVM will interact with the native gateway core.
 Design
 ------
 
-![](Design.png)
+![](HLD1.png)
 
 Java Module Host
 ----------------
@@ -21,7 +21,8 @@ The **Java Module Host** is a C module that
 1.  Creates the JVM (Java Virtual Machine) the first time a Java module is
     attempting to connect to the gateway.
 
-2.  Brokers calls **to** the Java module (create, destroy, receive).
+2.  Brokers calls **to** the Java module (create, destroy, receive) and
+    facilitates publishing **from** the Java module to the native Message Bus.
 
 Because [JNI](http://docs.oracle.com/javase/8/docs/technotes/guides/jni/) (Java
 Native Interface) only allows one JVM instance per process, the **Java Module
@@ -30,14 +31,15 @@ Subsequent attempts to load additional Java modules will load and run those
 modules in the same JVM that was originally created. The JSON configuration for
 this module will be similar to the configuration for the Node Module Host:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ json
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ json
 {
     "modules": [
         {
             "module name": "java_poller",
-            "module path": "/path/to/java_module_host.so|.dll",
+            "module path": "/path/to/java_module_host_hl.so|.dll",
             "args": {
                 "class_path": "/path/to/relevant/class/files",
+                "library_path": "/path/to/dir/with/java_module_host_hl.so|.dll"
                 "class_name": "Poller",
                 "args": {
                     "frequency": 30
@@ -57,35 +59,6 @@ this module will be similar to the configuration for the Node Module Host:
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-or:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ json
-{
-    "modules": [
-        {
-            "module name": "java_poller",
-            "module path": "/path/to/java_module_host.so|.dll",
-            "tags": ["java"],
-            "args": {
-                "class_path": "/path/to/relevant/class/files",
-                "class_name": "Poller",
-                "args": {
-                    "frequency": 30
-                }
-            }
-        }
-    ]
-}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-*You might have noticed a tags section. When processing the input JSON
-configuration file, the Gateway SDK will insert everything within the JSON
-object for the specified tag within the tags array into the args section for the
-corresponding module (please see \_\_\_\_ for more detailed guidance on
-constructing a JSON configuration).*
-
- 
-
 As usual, the `module path` specifies the path to the DLL/SO that implements the
 **Java Module Host**. The `args.class_path` specifies the path to the directory
 where all necessary Java class files are located, `args.class_name` is the name
@@ -101,20 +74,19 @@ The **Java Module Host** will handle calling into the gateway module written in
 Java when necessary, therefore each module written in Java must implement the
 same `IGatewayModule` interface shown below:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ java
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ java
 public interface IGatewayModule {
 
     /**
      * The create method is called by the subclass constructor when the native 
      * Gateway creates the Module. The constructor
      * should save both the {@code moduleAddr} and {@code bus} parameters.
      *
-     * @param moduleAddr The address of the native module pointer
      * @param bus The {@link MessageBus} to which this Module belongs
      * @param configuration The configuration for this module represented as a JSON
      * string
      */
-    void create(long moduleAddr, MessageBus bus, String configuration);
+    void create(MessageBus bus, String configuration);
 
     /**
      * The destroy method is called on a {@link GatewayModule} before it is about 
@@ -134,9 +106,9 @@ public interface IGatewayModule {
      * The destroy() and receive() methods are guaranteed to not be called 
      * simultaneously.
      *
-     * @param buffer The message content
+     * @param source The message content
      */
-    void receive(byte[] buffer);
+    void receive(byte[] source);
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -163,20 +135,19 @@ gateway, it:
 -   Constructs a `MessageBus` Java object using the `MESSAGE_BUS_HANDLE`.
 
 -   Finds the module’s class with the name specified by the `args.class_name`,
-    invokes the constructor passing in the `MODULE_HANDLE`, `MessageBus` object,
-    the JSON args string for that module, and creates the Java module.
+    invokes the constructor passing in the `MessageBus` object and the JSON args
+    string for that module, and creates the Java module.
 
--   Gets a global reference to the newly created `GatewayModule` object to be saved by
-    the `JAVA_MODULE_HOST_HANDLE`.
+-   Gets a global reference to the newly created `GatewayModule` object to be
+    saved by the `JAVA_MODULE_HOST_HANDLE`.
 
 ### Module\_Receive
 
 When the **Java Module Host**’s `Module_Receive` function is invoked by the
 gateway, it:
 
 -   Serializes the `MESSAGE_HANDLE` content and properties and invokes the
-    `receive` method implemented by the Java module with the `MODULE_HANDLE` and
-    the serialized message.
+    `receive` method implemented by the Java module with the serialized message.
 
 ### Module\_Destroy
 
@@ -194,12 +165,10 @@ gateway, it:
 Communication **FROM** the Java module
 --------------------------------------
 
-As previously mentioned, the **Java Module Host** will only handle communication
-from the native gateway process **to** the Java module. In order to communicate
-**from** the Java module to the native gateway process, the `MessageBus` class
-must be used. The `MessageBus` class provides a method to publish messages onto
-the native Message Bus and loads a dynamic library that implements expected
-functions for publishing onto the native Message Bus. So, the above diagram
-should look a bit more like this:
+In order to communicate **from** the Java module to the native gateway process,
+the `MessageBus` class must be used. The `MessageBus` class provides a method to
+publish messages onto the native Message Bus and loads a dynamic library that
+implements expected functions for publishing onto the native Message Bus. So,
+the above diagram should look a bit more like this:
 
-![](Design2.png)
+![](HLD2.png)

bindings/java/devdoc/Design2.png

@@ -41,4 +41,4 @@ public byte[] toByteArray();
 ```
 **SRS_JAVA_MESSAGE_14_004: [** The function shall serialize the Message content and properties according to the specification in [message.h](../../../../../../../../../core/devdoc/message_requirements.md) **]**
 
-**SRS_JAVA_MESSAGE_14_005: [** The function shall return `null` if the Message could not be serialized. **]**
+**SRS_JAVA_MESSAGE_14_005: [** The function shall return throw an IOException if the Message could not be serialized. **]**