Docs

Docs

Remote Procedure Calls

Calling client-side functions from the server, and server-side methods from the client.

Remote procedure calls (RPCs) are a way to run procedures or subroutines in a different address space, typically on another machine. Vaadin handles server-client communication by allowing RPC calls from the server to the client — and vice versa.

Calling Client-Side Functions from the Server

Use the Element API to call client-side functions from the server. This is covered in the Calling JavaScript from the Server reference guide.

Example 1. Calling the this.clearSelection() JavaScript function from the server side
Source code
Java
public void clearSelection() {
    getElement().callJsFunction("clearSelection");
}

Calling Server-Side Methods from the Client

The @ClientCallable annotation allows you to invoke a server-side method from the client side.

Any method in the component class annotated with @ClientCallable can be called from the client side using element.$server.methodName(args), where element is the root element of the component.

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

  • boolean, int, double, their boxed types (i.e., Boolean, Integer, Double);

  • String;

  • JsonNode;

  • Bean/DTO types that can be deserialized from JSON using Jackson;

  • Collections such as List and Map with proper generic types; and

  • enumeration types mapped to strings on the client side

Example 2. Making the getGreeting(String) method callable from the client side
Source code
Java
@ClientCallable
public String getGreeting(String name) {
    return "Hello " + name;
}

Receiving JSON Data

You can receive complex JSON data from the client by using Jackson’s JsonNode types as method parameters.

Example 3. Receiving a JSON object from the client
Source code
Java
@ClientCallable
public void saveSettings(JsonNode settings) {
    String theme = settings.get("theme").asText();
    int fontSize = settings.get("fontSize").asInt();
    // Process settings...
}

The client-side code can pass a JavaScript object directly:

Source code
JavaScript
this.$server.saveSettings({ theme: "dark", fontSize: 14 });

Receiving Bean/DTO Types

You can receive data directly as Java beans or DTOs. The JSON data from the client is automatically deserialized using Jackson.

Example 4. Receiving a bean from the client
Source code
Java
public class UserSettings {
    private String theme;
    private int fontSize;

    // Getters and setters required for Jackson deserialization
    public String getTheme() { return theme; }
    public void setTheme(String theme) { this.theme = theme; }
    public int getFontSize() { return fontSize; }
    public void setFontSize(int fontSize) { this.fontSize = fontSize; }
}

@ClientCallable
public void saveSettings(UserSettings settings) {
    String theme = settings.getTheme();
    int fontSize = settings.getFontSize();
    // Process settings...
}

The client-side code passes the same JavaScript object:

Source code
JavaScript
this.$server.saveSettings({ theme: "dark", fontSize: 14 });

Returning JSON Data

You can also return JSON data from @ClientCallable methods.

Example 5. Returning a JSON object to the client
Source code
Java
import tools.jackson.databind.node.ObjectNode;
import com.vaadin.flow.internal.JacksonUtils;

@ClientCallable
public ObjectNode getUserInfo() {
    ObjectNode info = JacksonUtils.createObjectNode();
    info.put("name", "John Doe");
    info.put("role", "admin");
    info.put("loginCount", 42);
    return info;
}

The client receives the data as a regular JavaScript object:

Source code
JavaScript
const info = await this.$server.getUserInfo();
console.log(info.name); // "John Doe"

The client-side method returns a Promise, which is resolved asynchronously with the return value from the server. If the server-side return type is void, the promise is resolved with the return value null.

Example 6. Calling the getGreeting(String) method from a client-side async JavaScript function
Source code
JavaScript
async getServerGreeting() {
  let greeting = await this.$server.getGreeting("JavaScript");
  console.log(greeting);
}
Example 7. Calling the getGreeting(String) method from a client-side JavaScript function using a callback
Source code
JavaScript
getServerGreeting() {
  let greetingPromise = this.$server.getGreeting("JavaScript");
  greetingPromise.then(greeting => console.log(greeting));
}
Important
Hidden and Disabled Components
If a component is hidden or disabled, client-side method calls to the server are automatically blocked. See the Component Enabled State and Component Visibility reference guides for more information.

Server-Side Modality and @ClientCallable

If a component with a @ClientCallable method is underneath a modal dialog or component, it’s considered inert. That means it’s not available for interaction, including RPC calls.

If you want the @ClientCallable method to be available when a component is inert, you’ll need to annotate it with the @AllowInert annotation. Consult the Server-Side Modality reference guide for more information.

Example 8. Allowing calls to getGreeting() even when the component is inert
Source code
Java
@ClientCallable
@AllowInert
public String getGreeting(String name) {
    return "Hello " + name;
}

AB7EDF45-DB22-4560-AF27-FF1DC6944482