Create your first JHipster project
Previously in 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 explore the UI for administration and our entities.
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 August 15, 2019, this
11.0.4+11 for OpenJDK 11:
openjdk version "11.0.4" 2019-07-16 OpenJDK Runtime Environment AdoptOpenJDK (build 11.0.4+11) OpenJDK 64-Bit Server VM AdoptOpenJDK (build 11.0.4+11, mixed mode)
Installing Node.js & npm
Please download the LTS version of the Node.js installer. That is version 10.16.2 as of
August 15, 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
npm install -g npm to do so. This updates npm to version
6.10.3 as of August 15, 2019, as you can check
npm -v. 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
6.2.0 as of August 15, 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 a future tutorial installment. Suffice to say, this file now contains all the
information JHipster needs to generate our project.
Now open a command prompt/terminal and change to the newly-created
tutorial-jhipster-docker directory. Type
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
master 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
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] ----------------------------------------------------------
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! 🎉
Exploring the 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). o n 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.
Exploring the administration section
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 in another browser, 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!
Exploring the entities
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.
- The first page is the overview page where you see a table with all the entities. JHipster generated a table for us with all entity fields and three buttons for view, editing and deleting on the right. Please note that the table shows an image thumbnail in the Picture column. We also have download links in the Picture and Specification columns. Now where does all that data come from? This is “fake data” — a new feature in JHipster 6.0 (I know, but the JHipster picked that name, not me!). JHipster generates this “fake data” when the entity is first generated.
- Now click on the View button of a row to see the detail page. Just like in the overview page, you get all fields, the picture (now bigger) and download links. You also have Back and Edit buttons at the bottom:
- Now click on the Edit button at the bottom to get to the combined create & update page. In the screenshot below I demonstrate
three validation features:
- In the JDL file we used to generate the application, the Name field is set to a minimum length of 2. I just have one character there, hence the first error.
- The Price field must be greater than or equal to 0, so the “-10” leads to the second error.
- Because our form contains errors, the Save button at the very bottom is disabled.
Feel free to explore the other entities, they all use the same layout. This is the end of our application exploration.
This wraps up the second tutorial installment. What have we accomplished here?
- We installed the necessary software.
- We generated our first JHipster application.
- We explored the UI for administration and our entities.
Your project source code should look like
master” branch of the GitHub project.
Coming up next in 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 3
in the Tutorial: Better Java Projects Faster with JHipster and Docker series.
« Explore the JHipster code | How JHipster and Docker saved my first Angular Java project » | Start: How JHipster and Docker saved my first Angular Java project