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
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
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.
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
of May 19, 2019.
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:
Install the 64-bit or 32-bit Git for Windows Setup.
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
jhipster import-jdl simple-shop-app.jdl to create your first JHipster application using
- 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
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
directory. Then type
gradlew.bat (Windows) or
./gradlew (macOS) to start the application. This runs
the default Gradle target
- 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:
"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! 🎉
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_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
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
"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 generated fake data sits in
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:
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 “
Once you have fixed these fake data errors, press
[Ctl]-[C] in the terminal to stop Gradle and then run
./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
[Ctl]-[C] in the terminal to stop Gradle and then run
All the create / update screens should work now. Here is the product order as an example:
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
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!
Part 2 of 2
in the Tutorial: Better Java Projects Faster with JHipster and Docker series.
How JHipster and Docker saved my first Angular Java project » | Start: How JHipster and Docker saved my first Angular Java project