Getting started with Configuration Manager

This guide explains the minimal steps to integrate Configuration Manager in a new application.

Prepare the Application

A new application created on start.vaadin.com can be used as a starting point for this tutorial. Open the site, select an empty project, choose Spring Boot as the framework, and download the generated archive. Extract it, import it into your IDE of choice, and verify the application starts correctly by running the main class.

Add the AppJars Repository

AppJars artifacts are published to the public AppJars Maven repository. Add it to your pom.xml so that Maven can resolve the AppJars dependencies:

<repositories>
    <repository>
        <id>appjars</id>
        <name>AppJars Public Repository</name>
        <url>https://maven.appjars.com</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Add the Dependencies

Given that it is a monolithic application, the following dependencies representing the three layers of the appjar must be added:

<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-configuration-manager-flow</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-configuration-manager-data-impl</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-configuration-manager-business-impl</artifactId>
</dependency>

After adding them, build the application to confirm that the dependencies are resolved correctly.

Implement the User Provider

Configuration Manager needs to identify the currently authenticated user and retrieve the list of all usernames in the application. The appjar does not ship an implementation, so provide one by implementing the UserProvider interface and registering it as a Spring component:

@Component
public class AppUserProvider implements UserProvider {

    @Override
    public String getPrincipalUsername() {
        return SecurityContextHolder.getContext().getAuthentication().getName();
    }

    @Override
    public List<String> getAllUsernames() {
        // Return the list of all usernames in the application
        return userRepository.findAllUsernames();
    }
}

The import for UserProvider is com.appjars.configurationmanager.service.UserProvider.

• getPrincipalUsername: Returns the username of the currently logged-in user. This is used to display and save that user's personal configurations.
• getAllUsernames: Returns the full list of usernames available in the application. This is used in the administrator view to manage configurations on behalf of any user.

Configure the Router Layout

Inject the RouteConfigurer provided by Configuration Manager and configure the router layout in a @PostConstruct method so that the appjar views share the same layout as the rest of the application:

@Autowired
@Qualifier("ConfigurationManagerRouteConfigurer")
RouteConfigurer routeConfigurer;

@PostConstruct
public void configure() {
    routeConfigurer.setViewsRouterLayout(MainLayout.class);
}

The import for RouteConfigurer is com.appjars.configurationmanager.flow.util.RouteConfigurer.

Add the Views to the Navigation

Configuration Manager provides three views. Add them to the application's navigation menu by inserting the following snippet at the end of the method createNavigation() in MainLayout, before returning nav:

if (accessChecker.hasAccess(SystemConfigurationsListView.class)) {
    nav.addItem(new SideNavItem("System Configurations", SystemConfigurationsListView.class, LineAwesomeIcon.SLIDERS_H_SOLID.create()));
}
if (accessChecker.hasAccess(UsersConfigurationsListView.class)) {
    nav.addItem(new SideNavItem("User Configurations", UsersConfigurationsListView.class, LineAwesomeIcon.USERS_COG_SOLID.create()));
}
if (accessChecker.hasAccess(MyConfigurationsView.class)) {
    nav.addItem(new SideNavItem("My Configurations", MyConfigurationsView.class, LineAwesomeIcon.USER_COG_SOLID.create()));
}

The imports for the view classes are:

• com.appjars.configurationmanager.flow.view.SystemConfigurationsListView
• com.appjars.configurationmanager.flow.view.UsersConfigurationsListView
• com.appjars.configurationmanager.flow.view.MyConfigurationsView

The System Configurations and User Configurations views are intended for administrators. The My Configurations view is accessible to all authenticated users and shows only their own configuration values.

Configure Application Properties

Add the following properties to application.properties:

spring.jpa.hibernate.ddl-auto=update
spring.jpa.generate-ddl=true
spring.aop.proxy-target-class=false
vaadin.i18n.provider=com.appjars.utils.i18n.AppjarsI18nProvider

The spring.aop.proxy-target-class=false property is required for the appjar to function correctly.

Finally, add com.flowingcode and com.appjars to the list of whitelisted packages in application.properties:

vaadin.allowed-packages = com.vaadin,org.vaadin,dev.hilla,com.example.application,com.flowingcode,com.appjars

Testing the Application

Start the application by running the main Spring Boot class. After it starts, log in and navigate to System Configurations in the menu.

Create a new configuration entry by clicking the New configuration button, providing a key, a type, and a default value. Once saved, the entry appears in the grid, and the Edit value action changes its value at runtime without restarting the application.

To confirm that the value reaches application code, name the entry after a property the application already reads. For example, with a bean holding:

@Value("${com.myapp.report.pageSize:20}")
private int pageSize;

create a system configuration named com.myapp.report.pageSize of type INTEGER. Its value now takes precedence over both the fallback 20 and any value set in application.properties. Because a @Value field is resolved when its bean is created, the running instance keeps the value it started with; read the property through Environment.getProperty() to observe changes immediately, or see the Developer Guide for the optional restart mechanism.

Finally, navigate to My Configurations to verify that a user configuration is visible and editable from the user's own perspective.