Accessing Java Backend

A server-side Java endpoint is a backend method that is exposed for calling from client-side TypeScript code. An endpoint in Vaadin is a class that defines one or more public methods.

Vaadin bridges Java backend endpoints and a TypeScript frontend. It generates TypeScript clients to call the Java backend in a type-checkable way.

Warning
Vaadin endpoints depend on Spring Boot auto configuration.
They do not work if the auto configuration is disabled, for example, when you use @EnableWebMvc. As a workaround, remove the @EnableWebMvc annotation, as stated in Spring Boot documentation. If you have an idea how to make it more useful for you, please share it on GitHub.

Creating an Endpoint

An endpoint is a Java class annotated with @Endpoint:

import com.vaadin.flow.server.connect.Endpoint;
import com.vaadin.flow.server.auth.AnonymousAllowed;

/**
 * A Vaadin endpoint that counts numbers.
 */
@Endpoint
@AnonymousAllowed
public class CounterEndpoint {
    /**
     * A method that adds one to the argument.
     */
    public int addOne(int number) {
        return number + 1;
    }
}

When the application starts, Vaadin scans the classpath for @Endpoint-annotated classes. For each request to access a public method in a Vaadin endpoint, a permission check is carried out. @AnonymousAllowed means that Vaadin permits anyone to call the method from the client-side.

Please refer to the Security for configuring endpoint access.

TypeScript Modules

In JavaScript and TypeScript, modules are files that follow the module syntax. This syntax has the following properties:

  • Top-level declarations (variables, functions, classes, etc.) are scoped inside the module, meaning that they are by default not available outside it.

  • A module supports top-level export statements, which make declarations available to other modules.

  • A module supports top-level import statements, which load and execute other modules, and can bring exported declarations.

The following example demonstrates the City.ts module:

// Declare and export an interface
export default interface City {
  country: string;
}
// Import and use a declaration from another module
import { City } from './City';
const cityObject: City = {
    name: "Turku",
    country: "Finland"
};
// Note: cityObject is not exported, thus it is only available in this file

In Vaadin applications, the index.ts (or, optionally, index.js) file is also a module.

Modules Generated From Vaadin Endpoints

Fusion generates a TypeScript module for every Vaadin endpoint on the backend. Each such module exports all the methods in the endpoint.

You can either import an entire module at once or select individual endpoint methods. For example, the CounterEndpoint.ts could be used as in the following snippets:

// Other imports
import { CounterEndpoint } from 'Frontend/generated/CounterEndpoint';

// Other code
CounterEndpoint.addOne(1).then(result => console.log(result));
// Other imports
import { addOne } from 'Frontend/generated/CounterEndpoint';

// Other code
addOne(1).then(result => console.log(result));
Note
The “Frontend” directory alias

The 'Frontend/' path prefix is an alias for the {project.basedir}/frontend directory in your application project.

Vaadin has this path alias in the default TypeScript compiler configuration (tsconfig.json), as well as in the generated webpack configuration file (webpack.generated.js).

Using this path alias is recommended, as it allows for absolute import paths, rather than traversing the directory hierarchy in relative imports.

Fusion generates the TypeScript modules automatically when you compile the application, as well as when the application is running in development mode.

By default, the generated files are located under {project.basedir}/frontend/generated. You can change the folder by providing the path for the generator in the generatedFrontendDirectory property for Vaadin Maven plugin.

Vaadin takes care of type conversion between Java and TypeScript types. For more information about supported types, see Type Conversion.

Example TypeScript Module Contents

For example, the generated TypeScript module for the Java endpoint defined in CounterEndpoint.java would look as follows:

/**
 * A Vaadin endpoint that counts numbers.
 *
 * This module has been generated from CounterEndpoint.java
 * @module CounterEndpoint
 */

import client from 'Frontend/connect-client.default';

/**
 * A method that adds one to the argument.
 *
 * @param number
 */
export async function addOne(number: number) {
  return await client.call('CounterEndpoint', 'addOne', {number});
}

Code Completion in IDEs

As you can see in the CounterEndpoint.ts example above, the Javadoc for the @Endpoint class is copied to the generated TypeScript file, and the type definitions are maintained. This helps code completion work at least in Visual Studio Code and IntelliJ IDEA Ultimate Edition.

Code Completion in Visual Studio Code

Code-completion