JBoss Dashbuilder


This article is a supplement of Dashbuilder’s document on dashbuilder.org and github.com/kylinsoong/dashboard-builder, primary purpose including:

Deploy dashboard-builder to WildFly

Build from source code

$ git clone git@github.com:kylinsoong/dashboard-builder.git
$ cd dashboard-builder/
$ mvn clean install -P h2,jetty -DskipTests
$ cd builder/
$ mvn clean install

Execute above commands will generate dashbuilder-VERSION-wildflyX.war under ‘dashboard-builder/builder/target’ folder, this war need deploy to a running WildFly Server.

Create User

Navigate to WildFly Home, execute the following commands to create two user:

$ ./bin/add-user.sh -a -u root -p password1! -g admin
$ ./bin/add-user.sh -a -u user -p password1! -g user

Run the Dashboard Builder

Once WildFly id running, dashbuilder-VERSION-wildflyX.war deployed success, login Dashboard Builder via


and use the recently created user root/password1! as below figure:

Dashboard Builder Login

Security configuration in web.xml


    <description>End user</description>

      <web-resource-name>Free access</web-resource-name>

      <web-resource-name>Restricted access</web-resource-name>


  • security-role - lists all the security roles used in the application, these roles should be mapped with roles exist in Application Server, in WildFly, map roles to a specific appication via security-domain which defined in jboss-web.xml file.

  • security-constraint - define the access privileges to a collection of resources using their URL mapping. web-resource-collection specifies a list of URL patterns, auth-constraint specifies whether authentication is to be used and names the roles authorized to perform the constrained requests.

  • login-config - define authentication method, in above configuration, Form-based authentication be defined, refer to below Form-Based Authentication for more details.

Form-Based Authentication

Compare with Basic Authentication pop up a raw login form, Form-Based Authentication allows the developer to control the look and feel of the login authentication screens by customizing the login screen and error pages that an HTTP browser presents to the end user. As below figure:

Form Based Login

When form-based authentication is declared, the following actions occur:

  • A client requests access to a protected resource.
  • If the client is unauthenticated, the server redirects the client to a login page.
  • The client submits the login form to the server.
  • The server attempts to authenticate the user. If authentication succeeds, redirect to requested protected resource, If authentication fails, redirected to an error page.

An example of login form:

<form method="POST" action="j_security_check">
    <input type="text" name="j_username">
    <input type="password" name="j_password">

Note that, the action of the login form must always be j_security_check, the input name must be j_username and the input password must be j_password.

Use Mysql with dashboard-builder


ControllerServlet is the entry point for UI request, all request(/workspace/, /jsp/, /kpi/*) will go to ControllerServlet, below figure is the sequence diagram of dashboard-builder login:

Login Process

web fragment

Started from Servlet 3.0, web-fragment.xml be introduced for pluggability of library jars which are packaged under WEB-INF/lib, The content of web-fragment.xml are almost same as web.xml, the web-fragment.xml be placed under classpath’s META-INF folder.

For example, in dashbuilder.war’s index.jsp define a jsp forward to Servlet

<jsp:forward page="workspace"/>

workspace define in WEB-INF/lib/dashboard-ui-core-6.4.0-SNAPSHOT.jar/META-INF/web-fragment.xml, rather than wewb.xml, the workspace definition looks:


ControllerServlet init

The following will dive into ControllerServlet init.

init App Directories

The following 3 directory path be formed and set to @ApplicationScoped scope entiry org.jboss.dashboard.Application:

  • baseAppDir -> standalone/deployments/dashbuilder.war
  • baseConfigDir -> standalone/deployments/dashbuilder.war/WEB-INF/etc
  • baseLibDir -> standalone/deployments/dashbuilder.war/WEB-INF/lib

Key code used to extract baseAppDir:

baseAppDir = new File(getServletContext().getRealPath("/")).getPath();

Startable Start

The Startable happens in ControllerServlet init, the sequence like

Startable Start

All 10 Startable be started including:


Hibernate cfg

Startable HibernateInitializer start initializes the Hibernate framework. It reads all the *.hbm.xml files and push them as part of the Hibernate configuration. Furthermore, initializes a SessionFactory object that will be used further by transactions.

dashbuilder.war’s total 16 .hbm.xml files be placed in 7 places:

1. dashbuilder.war/WEB-INFO/etc


2. dashbuilder.war/WEB-INF/lib/dashboard-security-VERSION.jar


3. dashbuilder.war/WEB-INF/lib/dashboard-commons-VERSION.jar


4. dashbuilder.war/WEB-INF/lib/dashboard-provider-core-VERSION.jar


5. dashbuilder.war/WEB-INF/lib/dashboard-ui-core-VERSION.jar


6. dashbuilder.war/WEB-INF/lib/dashboard-displayer-core-VERSION.jar


7. dashbuilder.war/WEB-INF/lib/dashboard-ui-panels-VERSION.jar


Using Hibernate Service API create SessionFactory

The key Hibernate API used in dashbuilder to init the SessionFactory looks

Hibernate SessionFactory Create API

  • 第 2 - 3 行实例化一个 org.hibernate.cfg.Configuration 对象,加载 Hibernate 配置文件 *.hbm.xml
  • 第 4 - 5 行通过 org.hibernate.service.ServiceRegistryBuilder 实例化一个 org.hibernate.service.ServiceRegistry
  • 第 6 行创建 SessionFactory

Completed runable code refer to HibernateInitializerH2

Using Hibernate Session execute JDBC operations

The org.hibernate.Session can be used to execute JDBC operations, it looks

Hibernate Session JDBC

  • 第 2 - 19 行实例化了一个 org.hibernate.jdbc.Work,execute(Connection connection) 方法用来执行 JDBC 操作
  • 第 20 行通过 sessionFactory 创建一个 org.hibernate.Session
  • 第 21 - 23 执行 Work,重写的 execute(Connection connection) 方法被调运