Create your first JHipster project

Previously on the “Better Java Projects Faster with JHipster and Docker” tutorial

In the first installment of the “Better Java Projects Faster with JHipster and Docker” tutorial, I laid out several common challenges that we Java developers face. You saw how JHipster helped me to overcome these challenges last year — and I showed you how you could master them, too. I also described how to customize the feature set of JHipster and defined situations where JHipster is probably not right for you.

Goals for this installment

In this second installment of the tutorial, we get hands-on: We produce a fully working, production-ready Java 11 application with Angular and Spring Boot, complete with unit tests and automated browser tests, ready for Continuous Integration and deployment into the cloud:

• We install the necessary software.
• We generate our first JHipster application.
• We fix some bugs in the generated code.

About the sample application

The sample application has a few entities of an online shop. It’s enough to demonstrate the features of JHipster and Docker, but it’s a far cry from a real online shop. 😄

The application is also available on GitHub. It has branches for every stage of every tutorial installment so that you can follow along if you ever get stuck.

The generated application uses two open source databases: the embedded database H2 for development and PostgreSQL for production. The front end is Angular. JHipster also generates unit tests for Java and Angular and end-to-end tests that run in the browser.

What kind of computer do you need?

You need a Windows PC or Mac for this tutorial. You must be able to install software on this machine, possibly with administrator or root access.

I tested this tutorial on the latest versions of Windows 10 and macOS Mojave (10.14). It should also work with older versions of both Windows and macOS, but I cannot vouch for that.

Installing Java 11

You need a Java 11 JDK. If you don‘t have one installed already, I recommend OpenJDK 11 from AdoptOpenJDK. The site has installers for Windows, Mac, and Linux. Please follow the instructions.

After the installation, please verify in a command prompt/terminal that java -version shows Java 11. As of May 19, 2019, this is 11.0.3+7 for OpenJDK 11:

openjdk version "11.0.3" 2019-04-16
OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.3+7)
OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.3+7, mixed mode)

Installing Node.js & npm

Node.js is a JavaScript runtime environment based on the Google Chrome JavaScript Engine. In other words: Node.js is “Tomcat for JavaScript.” npm refers to three different, but related things: A JavaScript library package format, a JavaScript build tool, and a public JavaScript component repository. So npm is “The JAR format and Maven and Maven Central for JavaScript.”

Please download the LTS version of the Node.js installer. That is version 10.15.13 as of May 19, 2019, and it installs both Node.js and npm. After the installation, please verify that node -v shows v10.15.3.

On macOS, you could also use Homebrew to install Node.js, but there are issues with that option. I recommend using the official installer instead.

npm is updated frequently, independent of Node.js. That’s why I highly recommend manually updating npm: In a command prompt/terminal, type npm install -g npm to do so. This updates npm to version 6.9.0 as of May 19, 2019. For macOS only: If npm spits out “cannot write” errors, then try sudo npm install -g npm for the update.

Installing JHipster

With npm in place, you can finally install JHipster: npm install -g generator-jhipster. Please verify the installation in a command prompt/terminal with jhipster --version. This shows version 6.0.1 as of May 19, 2019.

Installing Git

Git is the most popular source control system. You need it here because JHipster creates a Git project and actively uses Git during upgrades (where JHipster creates and merges a branch).

If you don’t have Git installed already, then please install it:

• Windows
  Install the 64-bit or 32-bit Git for Windows Setup.
• macOS
  If you have Homebrew installed, then go for brew install git. Otherwise, use the macOS installer.

Creating the application

Now we are finally ready to generate our first JHipster application!

Please create a tutorial-jhipster-docker directory on your computer for our starter project. Then create a file called simple-shop-app.jdl in that directory and paste the content from GitHub into it. We will examine this file in more detail in the next tutorial installment. It will contain all the information JHipster needs (for now) for our project.

Now open a command prompt/terminal and change to the newly-created tutorial-jhipster-docker directory. Type jhipster import-jdl simple-shop-app.jdl to create your first JHipster application using these steps:

• Source file generation
  JHipster creates source files for Spring Boot and Angular, configuration files, and build files for Gradle and npm.
• npm module installation
  Angular projects use many npm libraries. npm downloads them (through npm install), which takes a couple of minutes.
• Git project creation
  The final step initializes a local Git project.

If everything goes fine, then you see the following output in your terminal:

[...]

I'm all done. Running npm install for you to install the required
dependencies. If this fails, try running the command yourself.

[...]

Application successfully committed to Git.

[...]

Server application generated successfully.

[...]

Client application generated successfully.

[...]

Entity Product generated successfully.
Entity Address generated successfully.
Entity ShoppingOrder generated successfully.
Entity ProductOrder generated successfully.
Entity Shipment generated successfully.

[...]

INFO! Congratulations, JHipster execution is complete!
INFO! Deployment: child process exited with code 0

Congratulations — you just created your first JHipster project! 🎉

Your project should now have the same files as the GitHub project on the t-02-start branch. Note: Git ignores the two build directories (node_modules for npm and build for Gradle).

Running the application

Now let’s run the application we just created. Technically, we have a Spring Boot application with an embedded Angular front end and Gradle as the build system. JHipster allows you to use Maven, too, but I like Gradle better because it’s both more compact and more convenient to extend and customize. You don’t need to install Gradle, though, since the application uses the so-called “Gradle wrapper.” This is a batch file for Windows and a shell script for macOS / Linux which downloads a specific Gradle version on the fly if need be.

So please go back to the command prompt/terminal and the same tutorial-jhipster-docker directory. Then type gradlew.bat (Windows) or ./gradlew (macOS) to start the application. This runs the default Gradle target bootRun which

• downloads missing npm packages,
• builds the Angular application,
• generates Java resources (like mapper classes for Data Transfer Objects),
• compiles the Java code, and
• starts the Spring Boot application on port 8080.

If everything works well, then you see the following output in your command prompt/terminal:

----------------------------------------------------------
        Application 'my_simple_shop' is running! Access URLs:
        Local:          http://localhost:8080/
        External:       http://[your IP address]:8080/
        Profile(s):     [dev, swagger]
----------------------------------------------------------

You will see an error message during start-up: org.h2.jdbc.JdbcSQLSyntaxErrorException: Column "ORDER_ID" not found. We will attend to this later.

Now open http://127.0.0.1:8080 in your browser. The application loads and you should see this screen:

You may see a different “Hipster image.” JHipster picks one randomly out of a collection of four.

Congratulations — you just ran your first JHipster project! 🎉

Application layout

Let’s look at the front end application layout in more detail:

• In the top left, you find the application name “My_simple_shop” (defined in the localization resource bundle), the version number “v0.0.1-SNAPSHOT” (which is the Gradle project version number), and the red “Development” banner (which reminds you that you run the “dev” profile in Spring Boot).
• On the top right, you have the nav bar. There, you can switch languages (“Language”) and log in (“Account”).
• A JHipster logo and some explanations take up the main content area.
• The footer (“This is your footer”) is where it belongs – at the bottom.

The application has a responsive layout. Here’s the same application on an iPhone 6-size device, rendered by Chrome on the desktop and stitched together from two screenshots:

That already looks pretty solid: The nav bar turned into the (in)famous “hamburger menu,” and the main area changed to a single column layout. The application name and version are too long, though, and push the hamburger menu to a second line.

A whole lot of administration

JHipster created two default users: admin / admin and user / user, corresponding with the default Spring Security user roles of ROLE_ADMIN and ROLE_USER. You can probably guess what these users are allowed to do, so let’s log in as admin and look at the administration menu:

In the first installment of this tutorial, I stated:

we now sometimes have to build administration and scalability features that we used to take for granted.

When it comes to administration, JHipster already did all the hard work for us, giving us many features for free! Let’s take a look at them one at a time.

In “User management,” you do exactly what you expect — manage users:

We already mentioned the admin and user users. The system user comes into play for background tasks and database set-up.

“User tracker” shows you in real-time which other users are logged in and what page they’re on:

Here we see the user login active on the product page.

Next are the “Application Metrics”: JVM statistics, garbage collection information, HTTP & REST endpoint statistics, Hibernate cache information, and JDBC connection pool statistics.

The “Health Checks” tell you about free disk space and whether your database is OK. Details lurk behind the eye icon:

The “Configuration” screen lists all your “code settings”: Spring configuration, environment variables, configuration files, and even Git properties. This screenshot shows just the tip of the iceberg:

“Audits” shows you who logged in when, including failed attempts:

The “Logs” contains a fantastic troubleshooting tool: You can set the log level of every single Java class in your application in real-time:

So why is that useful again? Let’s imagine your application has a bug in production, and you need to find out what’s going on. Since your methods log their input parameters, you can find out through the log file. Case closed! Well, not so fast: Your methods log at DEBUG level — and in production, you run at INFO level, so the input parameters you need so desperately don’t appear in the log file. Now what?

You change the log level to DEBUG in your config file, restart the application, reproduce the error, change the config file log level back to INFO again, and restart the application once more. That’s two config file changes and two restarts – which is inconvenient at best and disastrous at worst, if you make a wrong change to the config file.

But with this screen, you simply change the log level of the classes you need to DEBUG, reproduce the error, and then change the log level back to INFO. No restarts, no config file changes, no wasted time! I spent years in production support and would have given my right arm for such a feature!

“API” lists all the REST endpoints in Spring Boot. This includes the endpoints for built-in functionality (such as the administration area) and the endpoints created for our data model in the JDL file. Below you see the details of the “Address” API:

The final entry, “Database,” is only available in the “dev” profile and leads to the web client of the embedded H2 database. It has the database tables of our application on the left, a SQL statement on the right, and the statement result at the bottom:

This concludes our exploration of all the administration features — which JHipster gives us for free!

Fixing the fake data

A new feature in JHipster 6.0 is the creation of fake data for your data model. Unfortunately, that doesn’t yet work perfectly. As a result, you got the org.h2.jdbc.JdbcSQLSyntaxErrorException: Column "ORDER_ID" not found error message during start-up, which I mentioned earlier.

To check the impact of this bug, please go to the “Entities” menu in the application. That menu contains the overview pages of all the entities that were generated from our data model. Please select “Product.” This shows you all the products — but it’s empty now because the fake data didn’t load:

Next, try “Addresses.” That overview doesn’t even appear because the database table doesn’t exist: The error loading the fake product data prevented its creation:

Let’s fix that. On the GitHub version of this tutorial application, this bug is already fixed on the “t-02-data-fixed” branch.

The generated fake data sits in the “src/main/resources/config/liquibase/data/” directory. There are two errors for sure:

• “product.csv” has an “order_id” column which is wrong.
• “shopping_order_.csv” has “orders_id_” and “shipment_id” columns which are also wrong.

You can either fix these errors manually in your files, or you can paste in my fixed versions from the “t-02-data-fixed” branch on GitHub:

• “product.csv” fixed
• “shopping_order_.csv” fixed

The third error, at least in my data, was in the “shipment.csv” file. Its data violated the unique constraint on the “order_id” column and produced a Unique index or primary key violation: "PUBLIC.UX_SHIPMENT_ORDER_ID_INDEX_F ON PUBLIC.SHIPMENT(ORDER_ID) VALUES X" error during start-up. Again, you can either fix these errors manually in your file, or you can paste in my fixed version of the “shipment.csv” file.

Once you have fixed these fake data errors, press [Ctl]-[C] in the terminal to stop Gradle and then run gradlew.bat / ./gradlew again. All errors should be eliminated, and you can now inspect all entities, such as the product orders:

Here is the detail view of an entity which you can reach from the “View” button:

Fixing the update screens

Now, if you try to create new entities or update existing ones, you’ll find that unfortunately most update screens don’t fully work, either. The dropdown fields for other entities have issues: Some use the wrong field name in the validation logic, others have some misplaced code fragments. It’s best if you replace the files in the “src/main/webapp/app/entities” directory your project with the ones from the “t-02-finish” branch:

• “address/address-update.component.html“
• “product/product-update.component.html“
• “product-order/product-order-update.component.html“
• “shipment/shipment-update.component.html“
• “shopping-order/shopping-order-update.component.html“

Now press [Ctl]-[C] in the terminal to stop Gradle and then run gradlew.bat / ./gradlew again. All the create / update screens should work now. Here is the product order as an example:

Wrap-up

This wraps up the second tutorial installment. We first installed all the software we need. Then we generated and ran the JHipster application. Next, we explored its administration and entity sections. Finally, we fixed issues with the fake data and in the update screens. Your project source code should look like the “t-02-finish” branch of the GitHub project.

Coming up next on the “Better Java Projects Faster with JHipster and Docker” tutorial

In the next installment, we’ll open and run the project in both Eclipse and IntelliJ. We’ll also explore the source code. Stay tuned!