1. Project Setup

In this chapter you will go through a few simple steps to set up a new project. Take a quick tour and learn how the project is structured and how to find essential components. Try to run your project to get familiar with pre-built features and learn what is happening behind the scenes.

Setting Up Development Environment

First, check system requirements and install Jmix Studio as described in the Setup section.

In this tutorial, we assume that you have a commercial or trial subscription for Jmix Studio. The Studio subscription gives access to visual editors and code generation capabilities that save time and help to learn Jmix features.

When you run Jmix Studio for the first time, it automatically obtains a trial subscription which is valid for 28 days. After it expires, you will be able to use the free version of Studio or purchase a commercial subscription.

You can manage the commercial or trial subscription after opening a Jmix project, see more information in the Subscription section.

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 11 or 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: Single Module 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 up to several minutes. 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.

But don’t miss the notification about the Jmix trial subscription! You need to accept it.

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

create project 5

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 application.properties file which defines database connection parameters, logging levels and other properties:

    explore project 2

  • 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 registered data stores and their Liquibase changelogs:

    explore project 4

    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 screens, as well as 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 screens:

    • LoginScreen accepts username and password for user authentication.

    • MainScreen is a screen which is opened to the user after login. It has a main menu and can open other screens inside.

    • User.browse and User.edit are CRUD screens for the User entity. In Jmix, by convention, browse suffix means a screen displaying the list of entities, and edit means a screen editing a single entity instance.

  • The Security section shows a list of roles. The new project contains a single FullAccessRole which is assigned to the admin user:

    explore project 7

  • 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

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 screen:

run app 5

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

In the main menu, click Application → Users:

run app 6

It’s the Users.browse screen 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.

  • 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.