DashBuilder is a great tool to author dashboards that can consume and display data from many sources, i.e. Prometheus, JDBC, Kie Server, and others. These dashboards can be later exported to a ZIP file and then be executed on DashBuilder Runtime.
Recently, we added a new alternative to create those dashboards: a pure Java API. The Java API exposes our existing builders and factories for data sets and visual components, but it also brings a new set of components for pages and navigation.
In this post, we will introduce the DashBuilder Java DSL (Domain Specific Language) API and teach you how to get started with it.
Dashbuider DSL API
The API has 5 main core components. Let’s take a look at those:
The API for data sets has as entry point the class org.dashbuilder.dataset.def.DataSetDefFactory which allows you to create your own data set definition. You can also pure Java data set using the class DataSetFactory, for example:
It is also possible to build data sets from multiple sources, such as CSV, Prometheus, SQL, and many others. It is important to notice that the same data set can have a different representation using lookups, which can be understood as data sets transformation requests. We will explore this later.
Components can be used in a dashboard page to display a data set or static information. The entry point to create components is the class org.dashbuilder.dsl.factory.component.ComponentFactory.
From there you can refer to components in your local file system or build displayers components. For “displayer” components notice that we need a factory to build the settings, the factory is class: org.dashbuilder.displayer.DisplayerSettingsFactory, where you can build the settings for your displayer. Bear in mind that all classes that use a displayer will require a data set to be built, otherwise, an exception will be thrown when exporting the dashboard;
You can build pages composed of the components mentioned in 2. Pages have rows that can have columns and finally components. Using the class org.dashbuilder.dsl.factory.page.PageFactory allow make it easy for you to create any page component;
You can create the pages navigation using org.dashbuilder.dsl.factory.navigation.NavigationFactory. This class can be used to define the menu of pages that will be displayed in DashBuilder Runtime;
This is the class that glues everything. It can be created using org.dashbuilder.dsl.factory.dashboard.DashboardFactory.
Note: All these classes have builders that can be used instead of the factory
Finally, when the work is done you can export the dashboard using the class org.dashbuilder.dsl.serialization.DashboardExporter.
Hello World Dashboard
Let’s now, create a Hello world using our API:
- Java 11+
- Docker or podman
- Create a maven project in your favorite IDE or use the following command:
Make sure to update it with the properties, dependencies, and build the section from this pom.xml:
- Create the class PopulationDashboard.java in package org.kie.dashbuilder with the content as seen below; It creates a dashboard and exports it to a ZIP file.
- On the project root, create the following directory structure. Notice that dashboards are a directory.
Make sure Dockerfile has the content as shown below
This is how the project structure should look like:
- Run PopulationDashboard.java in your IDE or using the command mvn clean install exec:java. After it runs the file population.zip is generated in dashbuilder-runtime/dashboards directory. This is the Dashboard you created: To visualize the dashboard you must:
- Build the image. Inside dashbuilder-runtime directory build the image using the following docker/podman command
docker build -t dashbuilder-dev .
It will download DashBuilder runtime, so it may take a while. You must run this command once.
- Then run the image:
docker run -dp 8080:8080 -v ./dashboards:/tmp/dashbuilder/models:z dashbuilder-dev
Once it is running you can access localhost:8080 and login as admin/admin. Every time you run PopulationDashboard Java class, the dashboard will be automatically updated. When the work is done, you can use the generated ZIP in production by using Dashbuilder Runtime in Static mode with the provided ZIP.
ConclusionIn this post, we introduced the Java API to create dashboards for Dashbuilder. In the next post, we will introduce other data set types and data set lookup, so stay tuned!