com.smartgwt.client.docs

## Interface JavaScriptToJavaConversion

-     public interface JavaScriptToJavaConversion

  ### Converting JavaScript objects to Java

  Converting between native JavaScript objects and GWT Java objects is something the Smart GWT framework needs to do very frequently (see also `JavaToJavaScriptConversion`). It is less common for application code to do such conversions, but the need can arise. The `JSOHelper` class contains many utility methods for sophisticated conversion from native JS objects to GWT Java objects. This article describes the common rules used when such conversions are run.
  - Conversion is recursive; nested JavaScript objects and arrays will have their members converted as well
  - Circular references (where an object is referred to by its own children, grandchildren, etc) are not tolerated. If you try to convert a JS object that contains circular references, your program will crash
  - This general prohibition of circular references includes native browser objects such as HTML elements retrieved by the `getElementById()` API, amd common objects like `window` and the JSNI `$wnd` object. These DOM elements contain references to both parent and children, which are inherently circular
  - null values, including `undefined`, are returned as null
  - JavaScript strings are returned as Java `String`s
  - JavaScript numbers are returned as
    - Java `Double`s if the number contains a decimal point, else
    - Java `Integer`s if the number is in the range of an Integer (between -2147483648 and 2147483647 inclusive), else
    - Java `Long`s
  - JavaScript dates are returned as `java.util.Date`s
  - JavaScript arrays are converted by converting each array element according to the other rules described here, and then converting the results into either a Java `Object[]` or a `java.util.ArrayList`, depending on the value of the "listAsArray" parameter (an array if that param is true, an `ArrayList` if it is false)
  - JavaScript objects are converted as follows:
    - If the GWT condition "`object instanceof JavaScriptObject`" is true, the object itself is returned
    - If Smart GWT detects that the object has a GWT Java wrapper object created by Smart GWT, that GWT wrapper object is returned
    - If the object has a "_constructor" property set to "DateRange" convert to `DateRange`
    - If the object has a "_constructor" property set to "RelativeDate" convert to `RelativeDate`
    - If the object is an instance of the SmartClient `Canvas` class, return the result of calling `Canvas.getById(java.lang.String)`. This will result in a Smart GWT Java object equivalent to the SmartClient Canvas - for example a SmartClient `ListGrid` will be returned as a `ListGrid`
    - If the object has a "name" property and a "form" property such that `isc.isA.DynamicForm(object.form)` is true:
      - Create a DynamicForm object by passing the object's "form" property as a parameter to `DynamicForm.getOrCreateRef(JavaScriptObject)`
      - Return the result of calling getField() on that form, passing in the object's "name" property
      - This process means that SmartClient FormItems are returned as equivalent Smart GWT objects (subclasses of `FormItem`)
    - If the SmartClient call "`isc.isAn.Instance(object)`" returns true and the object has a `getClassName()` method, returns the result of passing the object as a parameter to `createInstance()`
    - If the SmartClient call "`isc.isA.Class(object)`" returns true and the object has a `getClassName()` method, returns the equivalent Java class if it exists; otherwise returns null, calling `getSmartGWTClass()`
    - If none of the above conversions apply, the JavaScript object will be converted to a Java `Map` by running each property of the JavaScript object through the conversion process. Note, if SmartClient detects that the object is the JS form of a `TreeNode` (which is done by checking for the presence of an internal-only property), the SmartClient method `isc.Tree.getCleanNodeData()` is called on it before conversion starts; this obtains a clean version of the node data, free of any additional properties scribbled on by the Tree