1. Project Setup

In this chapter you will go through a few simple steps to set up a new project. You will learn how to navigate the project structure and locate essential components. Once your project is set up, you will be able to run it and explore its pre-built features.

Setting Up Development Environment

Install Jmix Studio and JDK as described in the Setup section if you haven’t done it yet.

In this tutorial, we will use some premium Studio features such as visual designers and code generation capabilities. These features are available for free in small projects containing up to 10 entities and roles, such as the tutorial project.

When you run Jmix Studio for the first time, you should log in to the Jmix account, and after that a trial subscription for 28 days is activated. The subscription allows you to use the premium features in projects of any size. After the trial subscription expires, Studio will continue working without subscription, providing premium features only for small projects.

Creating Project

Run IntelliJ IDEA with Jmix Studio plugin installed, switch to the Projects tab and click New Project:

create project 1

On the first step of the New Project wizard, select Jmix Project in the list and leave default values in the Repository and Jmix version fields:

create project 2

In the Project JDK field, select a JDK version 17. If the field displays <No SDK>, select Download JDK in its dropdown list and follow further instructions to download and select a JDK.

Click Next.

On the next step of the New Project wizard, select the first project template from the list: Full-Stack Application (Java):

create project 3

Click Next.

On the last step of the New Project wizard, enter onboarding to the Project name field:

create project 4

The Base package field defines the Java package which will contain all classes and resources of the project. Keep the value suggested by the wizard (com.company.onboarding) to conform the code in the tutorial.

Project id is not required for an application, so leave the field empty.

Click Create.

After the project is created, IDE starts downloading dependencies and indexing the project. On the first launch, it may take significant time (up to 10 minutes or more, depending on your internet connection and computer power). Please wait until the progress indicator in the status bar disappears.

The IDE will show a number of notifications suggesting to download "pre-built shared indexes" and install additional plugins. You can safely refuse them.

Logging in to Jmix Account

After downloading dependencies and indexing a project for the first time, Studio will show the Jmix Sign In dialog. In this dialog, you should log in to your Jmix account or register the new one.

sign in dialog

Click on the Sign In / Register button. You will be redirected to the system browser.

login form

  • If you don’t have a Jmix account, click on the Register link. In the Registration form, fill in the First name, Last name, Email, and Password fields, accept the privacy policy and click on the Register button.

    The email address you entered will be used as your login and the primary email address for your account.

    After you have submitted the registration form, you should verify your email address to activate your account. Find the verification email in your inbox and click the link in the email to finish the registration.

  • If you already have a Jmix account, enter the Email and Password and click the Sign In button.

A new user automatically gets a trial subscription to evaluate the full capabilities of the Studio for 28 days.

jmix subscription

When the project is ready, and Jmix Studio is activated, IDE opens the Jmix tool window on the left and the Welcome page in the working area:

create project 5

If all progress indicators have disappeared, but you don’t see the Welcome page and Jmix tool window, do the following:

  • Open Gradle tool window available on the right side of the IDE.

  • Click Reload All Gradle Projects (refresh) tool button.

Exploring New Project

The Jmix tool window presents a structured view of the project. Let’s figure out what a newly created project contains.

  • In the Build Scripts section you can see the Gradle build files:

    explore project 1

  • The Configuration section contains the main application class OnboardingApplication and the application.properties file which defines database connection parameters, logging levels and other properties:

    explore project 2

    The OnboardingSecurityConfiguration class complements the standard security configurations provided by Jmix modules. You can configure custom API endpoint security by defining SecurityFilterChain beans within this class.

  • The Add-ons section displays the list of installed Jmix add-ons:

    explore project 3

    If you double-click on the Add-ons node, Studio will open a dialog window for managing add-ons in your project.

  • The Data Stores section displays the list of databases used in the project, and their Liquibase changelogs:

    explore project 4

    In the new project, the HSQL relational database is used by default. It stores data in the .jmix/hsqldb folder of the project.

    Liquibase changelogs are XML files describing the database schema changes.

    If you double-click on the Main Data Store node, you will see parameters of the database connection in a dialog window. These parameters are stored in the application.properties file.

  • The Data Model section displays all project entities. There is a single User entity in the new project:

    explore project 5

  • The User Interface section contains the project views, as well as the Themes node to manage custom CSS, the Message Bundle node for quick access to localized messages and the Main Menu node for opening the menu descriptor:

    explore project 6

    As you can see, the project already contains a few views:

    • LoginView accepts username and password for user authentication.

    • MainView opens after login and contains the main menu.

    • User.list and User.detail are CRUD views for the User entity. In Jmix, by convention, list suffix means a view displaying the list of entities, and detail means a view editing a single entity instance.

  • The Beans section displays Spring beans defined in the project.

    explore project 9

  • The Security section shows a list of roles. The new project contains the FullAccessRole which is assigned to the admin user and UiMinimalRole which gives minimal permissions to users:

    explore project 7

  • The Deployment section will let you quickly deploy a containerized application to the cloud:

    explore project 10

  • If you double-click on the Sources node, Studio will open the Project tool window with the usual view of the entire source code:

    explore project 8

    Navigate to the Jmix tool window by clicking on the tab located on the left side of the IDE window.

Running Application from IDE

You can run the new project right after opening it in the IDE and see the initial state of your application.

Starting Application

run app 1

Find the dropdown field showing Onboarding Jmix Application value in the main toolbar and click the Debug button (start debugger) next to it.

If you are using IntelliJ IDEA Ultimate, you may see one more item in the Run/Debug Configurations dropdown list, called OnboardingApplication and having a Spring Boot icon (spring boot) on the left. It is automatically added by the Spring Boot plugin bundled with the IDE. Don’t use it.

To run a Jmix application, always use a configuration marked with the Gradle icon (gradle).

Studio will show the warning about the data store and unapplied changelog files:

run app 2

What does it mean?

On each start of the application, Studio tries to bring the database schema in sync with the project data model. So when you change your entities and their attributes, Studio will automatically generate Liquibase changelogs for making appropriate changes in the database.

To generate a changelog, Studio needs a current schema to be present in the database. Then it compares the database schema with the current data model and generates a changelog for the difference.

At the moment, our database is empty (actually, in our default case of the file-based HSQL database, it doesn’t exist at all), so to generate a diff changelog, Studio first needs to create the database and execute all existing changelogs of the project. In the dialog, you can see the existing changelogs from the project dependencies (marked read only) and from the project itself (010-init-user.xml).

Click Execute and proceed.

You will see the execution of Liquibase changelogs by Studio in the Run tool window at the bottom:

run app 3

All existing changelogs have been executed, Studio has checked the database schema for differences with the data model and found nothing. This is expected: you haven’t made any changes in the data model yet.

Right after checking the database, Studio builds and runs the application. You will see the console output of the running application in the Debug tool window at the bottom:

run app 4

When the application is ready to work, you will see the following message in the console : Application started at http://localhost:8080

Entering Application

Open localhost:8080 in a web browser. You will see your application login view:

run app 5

The admin / admin credentials are already set in the username and password fields (you can remove them later), so just click Log in.

In the main menu, click Application → Users:

run app 6

It’s the Users.list view showing the list of User entities. Now it has only the admin user created in the database by the 010-init-user.xml changelog.

Stopping Application

To stop the running application, click Stop button (suspend) in the main toolbar:

run app 7

You will see the following messages in the Debug console:

run app 8

Don’t worry, it’s not actually an error. This is the expected behavior of the IDE.

Summary

In this section, you have set up the development environment and created a new project in the IDE.

You have learned that:

  • Jmix Studio is a plugin for IntelliJ IDEA.

  • The tutorial assumes that you have a commercial or trial subscription for Jmix Studio. A trial subscription is issued when logging in to Jmix account for the first time.

  • Studio has a wizard for creating new projects by templates.

  • Studio shows the project structure in the Jmix tool window.

  • The new project contains functionality for logging in to the application and managing users.

  • The new application can be started from the IDE right after creating the project.

  • The new project uses a file-based HSQL database which is automatically created and initialized at the first start.