Remote Procedure Calls

Remote procedure calls (RPCs) are a way to execute procedures or subroutines in a different address space, typically on another machine.

Vaadin Flow handles server-client communication by allowing RPC calls from the server to the client, and vice versa.

Calling Client-Side Methods From the Server

You can execute client-side methods from the server by accessing the Element API.

callJsFunction Method

The callJsFunction() method allows you to execute a client-side component function from the server side. The method accepts two parameters: the name of the function to call, and the arguments to pass to the function.

The arguments passed to the function must be of a type supported by the communication mechanism. The supported types are String, Boolean, Integer, Double, JsonValue, Element, and Component.

Example: Using the callJsFunction() method to execute the clearSelection() function.

public void clearSelection() {
    getElement().callJsFunction("clearSelection");
}

public void setExpanded(Component component) {
    getElement().callJsFunction("expand",
            component.getElement());
}

executeJs Method

You can also use the executeJs() method to execute JavaScript asynchronously from the server side. You can use this method in addition to the callJsFunction() method.

The executeJs() method accepts two parameters: the JavaScript expression to invoke, and the parameters to pass to the expression. Note that the given parameters are available as variables named $0, $1, and so on.

The arguments passed to the expression must be of a type supported by the communication mechanism. The supported types are String, Integer, Double, Boolean and Element.

Example: Using the executeJs() method.

public void complete() {
    getElement().executeJs("this.complete($0)", true);
}

It is also possible to call the executeJs() method to access methods and fields of a Web Component.

Return Values

The return value from the JavaScript function called using callJsFunction() or the value from a return statement in an executeJs expression can be accessed by adding a listener to the PendingJavaScriptResult instance returned from either method.

Example: Check if the browser supports Constructable Stylesheets.

public void checkConstructableStylesheets() {
    getElement().executeJs(
            "return 'adoptedStyleSheets' in document")
            .then(Boolean.class, supported -> {
                if (supported) {
                    System.out.println(
                            "Feature is supported");
                } else {
                    System.out.println(
                            "Feature is not supported");
                }
            });
}

Tip	If the return value is a JavaScript `Promise`, then a return value will be sent to the server only when the `Promise` is resolved.

Calling Server-Side Methods From the Client

@ClientCallable Annotation

The @ClientCallable annotation allows you to invoke a server-side method from the client side. It marks a method in a Component subclass that can be called from the client side using the element.$server.serverMethodName(args) notation. In client-side Polymer template code, this refers to the corresponding element, so that the calling convention is this.$server.serverMethodName(args).

You can use it anywhere in your client-side Polymer class implementation, and you can pass your own arguments in the method. Note that the types should match the method declaration on the server side. The supported argument types are:

boolean , int, double, their boxed types (Boolean , Integer, Double)
String
JsonValue
enumeration type which is addressed via a string value from the client-side JavaScript
TemplateModel property types (see Using Beans with a PolymerTemplate Model

The client-side method returns a Promise which will be resolved asynchronously with the return value from the server, or null if the server-side return type is void. You can wait for the result using Promise.then(). In an async function, the await keyword can also be used to wait for the result.

Example: Using this.$server.getGreeting() to call a server-side method and await the result.

async getServerGreeting() {
  let greeting = await this.$server.getGreeting("JavaScript");
  console.log(greeting);
}

Example: Using this.$server.getGreeting() to call a server-side method and wait for the result in a callback.

getServerGreeting() {
  let greetingPromise = this.$server.getGreeting("JavaScript");
  greetingPromise.then(greeting => console.log(greeting));
}

Example: Using the @ClientCallable annotation on the server side.

@ClientCallable
public String getGreeting(String name) {
    return "Hello " + name;
}

Important

Property changes, DOM events, client-delegate methods (methods annotated with @ClientCallable) and event-handler methods (PolymerTemplate methods annotated with @EventHandler) are blocked for disabled components.

AB7EDF45-DB22-4560-AF27-FF1DC6944482

Documentation