Package 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 Strings
• JavaScript numbers are returned as
  • Java Doubles if the number contains a decimal point, else
  • Java Integers if the number is in the range of an Integer (between -2147483648 and 2147483647 inclusive), else
  • Java Longs
• JavaScript dates are returned as java.util.Dates
• 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