Merge commit 'fde53e04d783df8d25c37e421ed5b83907a30db8' into HEAD

Author: az-iot-builder-01

.gitignore

@@ -181,11 +181,11 @@ c/common/tools/macro_utils_h_generator/macro_utils_h_generator.exe
 **/hg/
 
 # Java
-java/**/.idea/
-java/**/out/
-java/**/target/
-java/**/*.iml
-java/**/*dependency-reduced-pom.xml
+**/java/**/.idea/
+**/java/**/out/
+**/java/**/target/
+**/java/**/*.iml
+**/java/**/*dependency-reduced-pom.xml
 tools/jenkins-cli.jar
 
 # Node.js
@@ -197,13 +197,6 @@ tools/jenkins-cli.jar
 typings/**
 .vscode/**
 
-csharp/NuGet/*.exe
-csharp/NuGet/*.nupkg
-csharp/.vs/*
-service/java/.idea
-service/java/target
-service/java/iot.service.sdk.java.iml
-
 # ignore cmake build folder
 .cmake/**
 build/**

CMakeLists.txt

@@ -40,6 +40,10 @@ function(add_module_to_solution undecoratedModuleName)
         PROPERTIES FOLDER "Modules/${undecoratedModuleName}")
 endfunction()
 
+function(add_binding_to_solution bindingLanguage)
+    set_target_properties(${bindingLanguage} PROPERTIES FOLDER "Bindings")
+endfunction()
+    
 function(add_sample_to_solution sampleName)
     	set_target_properties(${sampleName} PROPERTIES FOLDER "AzureIoTGateway_Samples")
 endfunction()

bindings/java/devdoc/Design.png

@@ -0,0 +1,205 @@
+Java Binding High Level Design
+==============================
+
+Overview
+--------
+
+This document describes the high level design of the Java binding mechanism used
+by the Azure IoT Gateway SDK. It details how Java modules running inside of the
+JVM will interact with the native gateway core.
+
+Design
+------
+
+![](Design.png)
+
+Java Module Host
+----------------
+
+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).
+
+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
+Host** will create a JVM **only once** when the first Java module is loading.
+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
+{
+    "modules": [
+        {
+            "module name": "java_poller",
+            "module path": "/path/to/java_module_host.so|.dll",
+            "args": {
+                "class_path": "/path/to/relevant/class/files",
+                "class_name": "Poller",
+                "args": {
+                    "frequency": 30
+                },
+                "jvm_options": {
+                    "version": 8,
+                    "debug": true,
+                    "debug_port": 9876,
+                    "verbose": false,
+                    "additional_options": [
+                        "-Djava.version=1.8"
+                    ]
+                }
+            }
+        }
+    ]
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+of the class that implements the module code, and finally `args.jvm_options` is
+a JSON object containing any options to be passed to the JVM upon creation.
+
+ 
+
+Gateway Module (Java)
+---------------------
+
+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
+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);
+
+    /**
+     * The destroy method is called on a {@link GatewayModule} before it is about 
+     * to be "destroyed" and removed from the gateway.
+     * Once a module is removed from the gateway, it may no longer send or receive 
+     * messages.
+     *
+     * The destroy() and receive() methods are guaranteed to not be called 
+     * simultaneously.
+     */
+    void destroy();
+
+    /**
+     * The receive method is called on a {@link GatewayModule} whenever it receives
+     * a message.
+     *
+     * The destroy() and receive() methods are guaranteed to not be called 
+     * simultaneously.
+     *
+     * @param buffer The message content
+     */
+    void receive(byte[] buffer);
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To simplify this, the Azure IoT Gateway SDK provides an abstract `GatewayModule`
+class which implements the `IGatewayModule` interface. Module-implementers
+should extend this abstract class when creating a module.
+
+ 
+
+Exactly like a standard gateway module written in C, the gateway will handle
+making calls to `Module_Create`, `Module_Receive`, and `Module_Destroy`. These
+three functions are implemented by the **Java Module Host** which handles the
+communication to the gateway module written in Java. Below is a description of
+what the **Java Module Host** will do in each of these cases:
+
+### Module\_Create
+
+When the **Java Module Host**’s `Module_Create` function is invoked by the
+gateway, it:
+
+-   Creates a JVM with the provided JVM configuration if this is the first Java
+    module added to the gateway.
+
+-   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.
+
+-   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.
+
+### Module\_Destroy
+
+When the **Java Module Host**’s `Module_Destroy` function is invoked by the
+gateway, it:
+
+-   Attaches the current thread to the JVM
+
+-   Invokes the `destroy` method implemented by the Java module.
+
+-   Deletes the global reference to the Java module object.
+
+-   Destroys the JVM if it is the last Java module to be destroyed.
+
+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:
+
+![](Design2.png)

bindings/java/devdoc/Design2.png

@@ -0,0 +1,50 @@
+# Module Requirements
+
+## Overview
+
+The GatewayModule abstract class must be extended by any module written in Java; all 
+Java modules must extend from the same abstract class. All methods to be
+implemented by the module-creator will be called by the gateway when necessary.
+
+## References
+
+[module.h](../../../../../../../../../core/devdoc/module.md)
+
+## Exposed API
+```java
+public abstract class GatewayModule {
+    protected GatewayModule(long address, MessageBus bus, String configuration);
+    abstract void receive(Message message);
+    abstract void destroy();
+}
+```
+
+## Module
+```java
+public GatewayModule(long address, MessageBus bus, String configuration);
+```
+**SRS_JAVA_GATEWAY_MODULE_14_001: [** The constructor shall save `address`, `bus`, 
+and `configuration` into class variables. **]**
+
+**SRS_JAVA_GATEWAY_MODULE_14_002: [** If `address` or `bus` is `null` the constructor 
+shall throw an IllegalArgumentException. **]**
+
+When extending this abstract class, the module-creator must create their own 
+constructor which calls this super constructor as the first statement.
+
+## receive
+```java
+public void receive(Message message);
+```
+This method must be implemented by the module-creator. The method takes the 
+native address of the `MODULE_HANDLE` and a byte array representing the serialized 
+`Message`. This method will be called when a message is received for this Module.
+
+## destroy
+```java
+public void destroy();
+```
+This method must be implemented by the module-creator. The method takes the
+native address of the `MODULE_HANDLE`. This method will be called when the module
+is about to be destroyed. Once destroyed, a module can no longer send or receive
+messages.

bindings/java/devdoc/java_binding_hld.md

@@ -0,0 +1 @@
+# MessageBus Requirements

bindings/java/devdoc/requirements_docs/com/microsoft/azure/gateway/core/gatewaymodule_requirements.md

@@ -0,0 +1,44 @@
+# Message Requirements
+
+## Overview
+
+A message to be used by the Java module implementer. A message will always be serialized before publishing to the native gateway message bus.
+
+## References
+
+[message.h](../../../../../../../../../core/devdoc/message_requirements.md)
+
+## Exposed API
+```java
+public final class Message implements Serializable{
+
+    private Map<String, String> properties;
+
+    private String content;
+
+    public Message(String content, Map<String, String> properties);
+    public Message(String content);
+    public Message(byte[] serializedMessage);
+    public Map<String, String> getProperties();
+    public String getContent();
+    public byte[] toByteArray();
+}
+```
+
+##  Message
+```java
+public Message(byte[] serializedMessage | String content[, Map<String, String> properties]);
+```
+**SRS_JAVA_MESSAGE_14_001: [** The constructor shall create a Message object by deserializing the byte array. **]**
+
+**SRS_JAVA_MESSAGE_14_002: [** If the byte array is malformed, the function shall throw an IllegalArgumentException. **]**
+
+**SRS_JAVA_MESSAGE_14_003: [** The constructor shall save the message content and properties map. **]**
+
+## toByteArray
+```java
+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. **]**