Remote Procedure Calls

Calling Client-side Methods from the Server
Calling Server-side Methods from the Client

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

You can call a server-side method from the client side using either the @EventHandler or @ClientCallable annotation.

@EventHandler Annotation

The @EventHandler annotation allows you to register a server-side method as an event handler. It publishes the annotated method and allows it to be invoked from the client side as a template event handler. See Handling User Events in a PolymerTemplate for more.

@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 can pass your own arguments in the method. Note that the types should match the method declaration on the server side.

The client-side method returns a Promise which will asynchronously be resolved 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 for waiting 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, event-handler methods (methods annotated with @EventHandler) and client-delegate methods (methods annotated with @ClientCallable) are blocked for disabled components.

2A2226FE-354E-4332-AFC5-3D4E0627B2B1

Docs