Build & Run

This page explains how to build, run and debug the console. We recommend to use Maven and the command line. This will work reliably across different environments and IDEs.

Build

If not already done, clone the code from https://github.com/hal/console/ or fork the repository into your own personal GitHub account.

For a full build use

mvn clean install

This includes the GWT compiler, which might take a while. If you just want to make sure that there are no compilation or test failures, you can skip the GWT compiler and use

mvn clean install -Dgwt.skipCompilation

Profiles

The maven build defines the following profiles:

  • docker Produces the docker container halconsole/hal which runs the console in standalone mode
  • esdoc Produces the JavaScript API documentation
  • i18n Compiles the console with language support for German, Spanish, French, Portuguese, Chinese and Japanese
  • prod Runs the GWT compiler using production settings. Minimizes the CSS and JavaScrip code.
  • release Signs the maven artifacts, builds and attaches Javadoc
  • site Builds the maven site
  • theme-eap Applies the EAP theme
  • theme-hal Applies the HAL theme
  • theme-wildfly Applies the WildFly theme

Scripts

HAL contains some scripts for typical development tasks. Here’s a short description of the scripts and what they’re used for:

  • app/refresh.sh: Rebuilds certain resources when running the GWT development mode (see below)
  • esdoc.sh: Builds and pushes the JavaScript API documentation
  • loc.sh: Calculates code metrics such as LoC per file type
  • release.sh: Builds and deploys HAL using profiles release,prod,theme-hal,docker and pushes the latest console build to https://hal.github.io/console/
  • snapshot.sh: Builds and deploys the latest snapshot
  • versionBump.sh: Bumps the version in all POMs and some documentation files
  • zanata.sh: Syncs the i18n resources with the Zanata translation service.

Run

HAL is a GWT application and as such it is served from a local Jetty server. As a one time prerequisite you need to add the URL of the local Jetty server as an allowed origin to your WildFly / JBoss EAP configuration:

Standalone Mode

/core-service=management/management-interface=http-interface:list-add(name=allowed-origins,value=http://localhost:8888)
reload

Domain Mode

/host=master/core-service=management/management-interface=http-interface:list-add(name=allowed-origins,value=http://localhost:8888)
reload --host=master

The main GWT application is located in the app folder. To run the console use

cd app
mvn gwt:devmode

This will start the development mode. Wait until you see a message like

00:00:15,703 [INFO] Code server started in 15.12 s ms

Then open http://localhost:8888/dev.html in your browser and connect to your WildFly / JBoss EAP instance as described in standalone mode.

Debug

Start the console as described in the previous chapter. GWT uses the SourceMaps standard to map the Java source code to the transpiled JavaScript code. This makes it possible to use the browser development tools for debugging.

In Chrome open the development tools and switch to the ‘Sources’ tab. Press ⌘ P and type the name of the Java source file you want to open.

Let’s say we want to debug the enable / disable action in the data source column in configuration. Open the class DataSourceColumn and put a breakpoint on the first line of method void setEnabled(ResourceAddress, boolean, SafeHtml) (should be line 285). Now select a data source like the default ‘ExampleDS’ data source and press the enable / disable link in the preview. The browser should stop at the specified line and you can use the development tools to inspect and change variables.

Inspect Variables

If you’re used to debug Java applications in your favorite IDE, the debugging experience in the browser development tools might feel strange at first. You can inspect simple types like boolean, numbers and strings. Support for native JavaScript types like arrays and objects is also very good. On the other hand Java types like lists or maps are not very well supported. In addition most variable names are suffixed with something like _0_g$. We recommend to inspect these variables using the console and call the toString() method on the respective object.

Develop

To apply changes made to Java code you just need to refresh the browser. GWT will detect the modifications and only transpile the changed sources.

Changes to other resources require a little bit more effort. To make it easier, you can use the script app/refresh.sh. Change to the app folder and call refresh.sh with one of the following parameters, depending what kind of resource you’ve modified:

  • less: Compile LESS stylesheets
  • html: Update HTML snippets
  • i18n: Process i18n resource bundles
  • mbui: Regenerate MBUI resources

After calling the script, refresh the browser to see your changes.