Merge pull request #1239 from NativeScript/niliev/masrsh

refactor: add marshalling examples

Author: NickIliev

docs/core-concepts/android-runtime/marshalling/java-to-js.md

@@ -8,15 +8,15 @@ position: 2
 # Java to JavaScript Conversion
 The article lists the available types in Java and how they are projected to JavaScript.
 
-### String & Character
+## String & Character
 Both [java.lang.String](http://developer.android.com/reference/java/lang/String.html) and [java.lang.Character](http://docs.oracle.com/javase/7/docs/api/java/lang/Character.html) types are projected as JavaScript [String](http://www.w3schools.com/jsref/jsref_obj_string.asp):
 
 ```javascript
 var file = new java.io.File("/path/to/file");
 var path = file.getPath(); // returns java.lang.String, converted to JS String
 ```
 
-### Boolean & Primitive boolean
+## Boolean & Primitive boolean
 Both the primitive [boolean](http://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html) and reference [java.lang.Boolean](http://docs.oracle.com/javase/7/docs/api/java/lang/Boolean.html) types are projected as JavaScript [Boolean](http://www.w3schools.com/jsref/jsref_obj_boolean.asp):
 
 ```javascript
@@ -25,47 +25,47 @@ var button = new android.widget.Button(context);
 var enabled = button.isEnabled(); // returns primitive boolean, converted to JS Boolean
 ```
 
-### Byte & Primitive byte
+## Byte & Primitive byte
 Both the primitive [byte](http://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html) and reference [java.lang.Byte](http://docs.oracle.com/javase/7/docs/api/java/lang/Byte.html) types are projected as JavaScript [Number](http://www.w3schools.com/jsref/jsref_obj_number.asp):
 
 ```javascript
 var byte = new java.lang.Byte("1");
 var jsByteValue = byte.byteValue(); // returns primitive byte, converted to Number
 ```
 
-### Short & Primitive short
+## Short & Primitive short
 Both the primitive [short](http://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html) and reference [java.lang.Short](http://docs.oracle.com/javase/7/docs/api/java/lang/Short.html) types are projected as JavaScript [Number](http://www.w3schools.com/jsref/jsref_obj_number.asp):
 
 ```javascript
 var short = new java.lang.Short("1");
 var jsShortValue = short.shortValue(); // returns primitive short, converted to Number
 ```
 
-### Integer & Primitive int
+## Integer & Primitive int
 Both the primitive [int](http://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html) and reference [java.lang.Integer](http://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html) types are projected as JavaScript [Number](http://www.w3schools.com/jsref/jsref_obj_number.asp):
 
 ```javascript
 var int = new java.lang.Integer("1");
 var jsIntValue = int.intValue(); // returns primitive int, converted to Number
 ```
 
-### Float & Primitive float
+## Float & Primitive float
 Both the primitive [float](http://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html) and reference [java.lang.Float](http://docs.oracle.com/javase/7/docs/api/java/lang/Float.html) types are projected as JavaScript [Number](http://www.w3schools.com/jsref/jsref_obj_number.asp):
 
 ```javascript
 var float = new java.lang.Float("1.5");
 var jsFloatValue = float.floatValue(); // returns primitive float, converted to Number
 ```
 
-### Double & Primitive double
+## Double & Primitive double
 Both the primitive [double](http://docs.oracle.com/javase/tutorial/java/nutsandbolts/datatypes.html) and reference [java.lang.Double](http://docs.oracle.com/javase/7/docs/api/java/lang/Double.html) types are projected as JavaScript [Number](http://www.w3schools.com/jsref/jsref_obj_number.asp):
 
 ```javascript
 var double = new java.lang.Double("1.5");
 var jsDoubleValue = double.doubleValue(); // returns primitive double, converted to Number
 ```
 
-### Long & Primitive long
+## Long & Primitive long
 [java.lang.Long](http://docs.oracle.com/javase/7/docs/api/java/lang/Long.html) and its primitive equivalent are special types which are projected to JavaScript by applying the following rules:
 
 * If the value is in the interval (-2^53, 2^53) then it is converted to [Number](http://www.w3schools.com/jsref/jsref_obj_number.asp)
@@ -92,7 +92,7 @@ var jsNumber = testClass.getLongNumber53Bits(); // result is JavaScript Number
 var specialObject = testClass.getLongNumber54Bits(); // result is the special object described above
 ```
 
-### Array
+## Array
 Array in Java is a special [java.lang.Object](http://docs.oracle.com/javase/7/docs/api/java/lang/Object.html) that have an implicit Class associated. A Java Array is projected to JavaScript as a special JavaScript proxy object with the following characteristics:
 
 * Has length property
@@ -108,6 +108,7 @@ var singleFile = files[0]; // the indexed getter callback is triggered and a pro
 
 >**Note:** A Java Array is intentionally not converted to a JavaScript [Array](http://www.w3schools.com/jsref/jsref_obj_array.asp) for the sake of performance, especially when it comes to large arrays.
 
+### Array of Objects
 
 Occasionally you have to create Java arrays from JavaScript. For this scenario we added method `create` to built-in JavaScript [`Array` object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array). Here are some examples how to use `Array.create` method:
 
@@ -126,7 +127,7 @@ Array.create(elementClassName, length)
 Array.create(javaClassCtorFunction, length)
 ```
 The first signature accepts `string` for `elementClassName`. This option is useful when you have to create Java array of primitive types (e.g. `char`, `boolean`, `byte`, `short`, `int`, `long`, `float` and `double`). It is also useful when you have to create Java jagged arrays. For this scenario `elementClassName` must be the standard JNI class notation. Here are some examples:
-```javascript
+```JavaScript
 // equivalent to int[][] jaggedIntArray2 = new int[10][];
 var jaggedIntArray2 = Array.create("[I", 10);
 
@@ -137,15 +138,48 @@ var jaggedBooleanArray3 = Array.create("[[Z", 10);
 var jaggedObjectArray4 = Array.create("[[[Ljava.lang.Object;", 10);
 ```
 The second signature uses `javaClassCtorFunction` which must the JavaScript constructor function for a given Java type. Here are some examples:
-```javascript
+```JavaScript
 // equivalent to String[] stringArr = new String[10];
 var stringArr = Array.create(java.lang.String, 10);
 
 // equivalent to Object[] objectArr = new Object[10];
 var objectArr = Array.create(java.lang.Object, 10);
 ```
 
-### Null
+### Array of Primitive Types
+The automatic marshalling works only for cases with arrays of objects. In cases where you have a method that takes an array of primitive types, you need to convert it as follows:
+```Java
+public static void myMethod(int[] someParam)
+```
+Then yoy need to invoke it as follows:
+```JavaScript
+let arr = Array.create("int", 3);
+arr[0] = 1;
+arr[1] = 2;
+arr[2] = 3;
+
+SomeObject.myMethod(arr); // assuming the method is accepting an array of primitive types
+```
+
+### Two-Dimensional Arrays of Primitive Types
+
+The above scenario gets more tricky with two-dimensional arrays. Consider a Java method that accepts as an argument a two-dimensional array:
+```Java
+public static void myMethod(java.lang.Integer[][] someParam)
+```
+The marshalled JavaScript code will look like this:
+```JavaScript
+let arr = Array.create("[Ljava.lang.Integer;", 2);
+let elements = Array.create("java.lang.Integer", 3);
+elements[0] = new java.lang.Integer(1);
+elements[1] = new java.lang.Integer(2);
+elements[2] = new java.lang.Integer(3);
+arr[0] = elements;
+
+SomeObject.myMethod(arr); // assuming the method is accepting a two-dimensional array of primitive types
+```
+
+## Null
 The Java [null literal](http://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.10.7) (or null pointer) is projected to JavaScript [Null](http://www.w3schools.com/js/js_typeof.asp):
 
 ```javascript
@@ -154,7 +188,7 @@ var button = new android.widget.Button(context);
 var background = button.getBackground(); // if there is no background drawable method will return JS null
 ```
 
-### Android Types
+## Android Types
 All Android-declared types are projected to JavaScript using the Package and Class proxies as described in [Accessing APIs](../metadata/accessing-packages.md)
 
 # See Also