Update AJS?.callFunction javadoc to reflect reality (#18990)

Change-Id: Ie53b535a2ae3c0e0ff5bb4b0516364c8817456d3

3 files changed, 32 insertions, 12 deletions

diff --git a/server/src/com/vaadin/server/AbstractJavaScriptExtension.java b/server/src/com/vaadin/server/AbstractJavaScriptExtension.java
index e9cf2c5e33..693f3a28c8 100644
--- a/server/src/com/vaadin/server/AbstractJavaScriptExtension.java
+++ b/server/src/com/vaadin/server/AbstractJavaScriptExtension.java
@@ -20,6 +20,9 @@ import com.vaadin.shared.JavaScriptExtensionState;
 import com.vaadin.shared.communication.ServerRpc;
 import com.vaadin.ui.JavaScriptFunction;
 
+import elemental.json.Json;
+import elemental.json.JsonValue;
+
 /**
  * Base class for Extensions with all client-side logic implemented using
  * JavaScript.
@@ -175,10 +178,13 @@ public abstract class AbstractJavaScriptExtension extends AbstractExtension {
 
     /**
      * Invoke a named function that the connector JavaScript has added to the
-     * JavaScript connector wrapper object. The arguments should only contain
-     * data types that can be represented in JavaScript including primitives,
-     * their boxed types, arrays, String, List, Set, Map, Connector and
-     * JavaBeans.
+     * JavaScript connector wrapper object. The arguments can be any boxed
+     * primitive type, String, {@link JsonValue} or arrays of any other
+     * supported type. Complex types (e.g. List, Set, Map, Connector or any
+     * JavaBean type) must be explicitly serialized to a {@link JsonValue}
+     * before sending. This can be done either with
+     * {@link JsonCodec#encode(Object, JsonValue, java.lang.reflect.Type, com.vaadin.ui.ConnectorTracker)}
+     * or using the factory methods in {@link Json}.
      * 
      * @param name
      *            the name of the function
diff --git a/server/src/com/vaadin/ui/AbstractJavaScriptComponent.java b/server/src/com/vaadin/ui/AbstractJavaScriptComponent.java
index 84023555bb..4463a6ee61 100644
--- a/server/src/com/vaadin/ui/AbstractJavaScriptComponent.java
+++ b/server/src/com/vaadin/ui/AbstractJavaScriptComponent.java
@@ -16,9 +16,13 @@
 package com.vaadin.ui;
 
 import com.vaadin.server.JavaScriptCallbackHelper;
+import com.vaadin.server.JsonCodec;
 import com.vaadin.shared.communication.ServerRpc;
 import com.vaadin.shared.ui.JavaScriptComponentState;
 
+import elemental.json.Json;
+import elemental.json.JsonValue;
+
 /**
  * Base class for Components with all client-side logic implemented using
  * JavaScript.
@@ -167,10 +171,13 @@ public abstract class AbstractJavaScriptComponent extends AbstractComponent {
 
     /**
      * Invoke a named function that the connector JavaScript has added to the
-     * JavaScript connector wrapper object. The arguments should only contain
-     * data types that can be represented in JavaScript including primitives,
-     * their boxed types, arrays, String, List, Set, Map, Connector and
-     * JavaBeans.
+     * JavaScript connector wrapper object. The arguments can be any boxed
+     * primitive type, String, {@link JsonValue} or arrays of any other
+     * supported type. Complex types (e.g. List, Set, Map, Connector or any
+     * JavaBean type) must be explicitly serialized to a {@link JsonValue}
+     * before sending. This can be done either with
+     * {@link JsonCodec#encode(Object, JsonValue, java.lang.reflect.Type, com.vaadin.ui.ConnectorTracker)}
+     * or using the factory methods in {@link Json}.
      * 
      * @param name
      *            the name of the function
diff --git a/server/src/com/vaadin/ui/renderers/AbstractJavaScriptRenderer.java b/server/src/com/vaadin/ui/renderers/AbstractJavaScriptRenderer.java
index 57e8130b29..66d501eb3f 100644
--- a/server/src/com/vaadin/ui/renderers/AbstractJavaScriptRenderer.java
+++ b/server/src/com/vaadin/ui/renderers/AbstractJavaScriptRenderer.java
@@ -17,11 +17,15 @@ package com.vaadin.ui.renderers;
 
 import com.vaadin.server.AbstractJavaScriptExtension;
 import com.vaadin.server.JavaScriptCallbackHelper;
+import com.vaadin.server.JsonCodec;
 import com.vaadin.shared.JavaScriptExtensionState;
 import com.vaadin.shared.communication.ServerRpc;
 import com.vaadin.ui.Grid.AbstractRenderer;
 import com.vaadin.ui.JavaScriptFunction;
 
+import elemental.json.Json;
+import elemental.json.JsonValue;
+
 /**
  * Base class for Renderers with all client-side logic implemented using
  * JavaScript.
@@ -141,10 +145,13 @@ public abstract class AbstractJavaScriptRenderer<T> extends AbstractRenderer<T>
 
     /**
      * Invoke a named function that the connector JavaScript has added to the
-     * JavaScript connector wrapper object. The arguments should only contain
-     * data types that can be represented in JavaScript including primitives,
-     * their boxed types, arrays, String, List, Set, Map, Connector and
-     * JavaBeans.
+     * JavaScript connector wrapper object. The arguments can be any boxed
+     * primitive type, String, {@link JsonValue} or arrays of any other
+     * supported type. Complex types (e.g. List, Set, Map, Connector or any
+     * JavaBean type) must be explicitly serialized to a {@link JsonValue}
+     * before sending. This can be done either with
+     * {@link JsonCodec#encode(Object, JsonValue, java.lang.reflect.Type, com.vaadin.ui.ConnectorTracker)}
+     * or using the factory methods in {@link Json}.
      * 
      * @param name
      *            the name of the function