Skip to content

Getting started with Data Query

This guide explains the minimal steps to integrate Data Query 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-data-query-flow</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-data-query-data-impl</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-data-query-business-impl</artifactId>
</dependency>

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

Configure the Router Layout

Inject the route configurer provided by Data Query 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("DataQueryRouteConfigurer")
DataQueryRouteConfigurer routeConfigurer;

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

The import for the route configurer is com.appjars.dataquery.flow.util.DataQueryRouteConfigurer.

Note

Unlike the other appjars, whose route configurer class is named RouteConfigurer in a package of its own, Data Query names the class DataQueryRouteConfigurer. The bean name is DataQueryRouteConfigurer, so the @Qualifier above matches; because the type is unique in the application context, the qualifier can also be omitted.

Add the Views to the Navigation

Data Query provides three management 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(QueryDefinitionListView.class)) {
    nav.addItem(new SideNavItem("Queries", QueryDefinitionListView.class, LineAwesomeIcon.DATABASE_SOLID.create()));
}
if (accessChecker.hasAccess(QueryCategoryListView.class)) {
    nav.addItem(new SideNavItem("Query Categories", QueryCategoryListView.class, LineAwesomeIcon.FOLDER_SOLID.create()));
}
if (accessChecker.hasAccess(DashboardListView.class)) {
    nav.addItem(new SideNavItem("Dashboards", DashboardListView.class, LineAwesomeIcon.CHART_BAR_SOLID.create()));
}

The imports for the view classes are:

  • com.appjars.dataquery.flow.view.QueryDefinitionListView
  • com.appjars.dataquery.flow.view.QueryCategoryListView
  • com.appjars.dataquery.flow.view.DashboardListView

The report view, the report designer and the runtime dashboard view are reached from these three, and from links inside reports, so they do not need menu entries of their own.

Warning

Every view the appjar provides is annotated @PermitAll, which means any authenticated user can reach the management views and define new queries. Because a query body is executed against the application's data source, restricting the management routes to administrators is a required part of the integration and is left to the host application's security configuration. See Restricting Access to the Management Views in the Developer Guide.

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

Enable the Connectors You Intend to Use

The SQL connector works with no further configuration: it uses the application's existing DataSource.

The HQL connector uses the application's EntityManager and is likewise available immediately. It reaches every mapped entity by default. If the domain model holds data that must not appear in a report, restrict it:

com.appjars.dataquery.hql.allowed-entities=OrderEntity,ProductEntity

The REST connector requires an allowlist of hosts before it will run at all. Until this property is set, no REST query executes:

com.appjars.dataquery.rest.allowed-hosts=api.example.com,*.internal.example.com

The full set of connector properties is documented in Configuration Properties.

Testing the Application

Start the application by running the main Spring Boot class, log in, and navigate to Queries in the menu.

Create a query definition: give it a key and a display name, leave the connector on SQL, and enter a statement against a table the application already has, using :name for any parameter — for example SELECT id AS order_id, total FROM orders WHERE total > :minimum. On the Parameters tab, add a parameter whose key is minimum with the type Double. On the Result Columns tab, add one column per selected alias — order_id as an integer and total as a double. Save the query.

Choose Execute from the row menu of the query. The report view opens with a Minimum field; enter a value and click Execute to see the results in a grid, sorted and exported as needed.