Working with Project

This section describes how to create a new project, open an existing one, and start the application.

Creating New Project

Studio provides a wizard to create new Jmix projects from scratch.

  1. Open New Project wizard from the main menu: File → New → Project. Also, you can click New Project in the welcome screen of IDE.

  2. Select Jmix Project in the dialog.

    new project create

    Configure the main project settings on this step:

    • You can accept the default repository that is specified in the Repository field, or select Custom repository and configure it.

    • Select Use local Maven repository if you want to use artifacts from the local repository.

    • Select the Jmix version to be used in the project. If you do not have any specific requirements, use the latest released version.

      For beta-testing or early accessing new Jmix framework features, you might want to use one of unstable Jmix framework versions, ones that end with BETA or SNAPSHOT suffixes. To see them in the Jmix version drop-down list, you need to select the Show unstable versions checkbox.

    • In the Project JDK field, select JDK corresponding to JAVA_HOME which is set in your environment. If you see the <No JDK> value, click Add JDK in the list and select the folder, where JDK is installed, for example, C:\Program Files\BellSoft\LibericaJDK-17 on Windows or /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home on macOS.

  3. On the next wizard step, select a template to be used for creating an empty project.

    new project templates

  4. In the next window, you can set the project’s name, location, and localization.

    new project name

    • Change value of the Project name field, if required. The name should contain only Latin letters, numbers, and underscores.

    • Project location is the path to the new project directory. You can select another directory by typing it in the field or clicking the button next to the field.

    • Base package is the base package for Java classes and resources. Choose the name of the package carefully. Later, you will be able to change the name and move classes and resources only manually.

    • Project id is optional. If it is set, Studio will use it as a prefix for entity, table and bean names. The project id must not be longer than 7 characters.

    • Use the Locales field to open an editor and add more supported locales to the project. You will be able to change them later if required.

  5. Click Finish. The empty project will be created in the specified directory, and Studio will start building the project information from Gradle files and indexing the project.

    If this is the first time you start working with a project in Jmix Studio, you should log in to the Jmix account.

    When the project synchronization and indexing process is completed, you will see the Jmix project tree in the Jmix Tool Window.

Now you can start working on the project.

Opening Existing Project

To open the project, do the following steps:

  1. Click Open in the welcome window of the IDE.

    new project welcome

    If another project is already opened, go File → Open from the main menu.

  2. In the file system dialog, select the project’s root folder containing the build.gradle file, select it and click OK.

    new project build

    When opening a composite project, make sure to navigate to the <project-name>-all aggregator project directory and open the build.gradle file within that directory:

    open composite project

  3. In the appeared dialog, select Open as Project.

    new project open

    Wait for Gradle synchronization and project indexing process to complete.

    If this is the first time you start working with a project in Jmix Studio, you should log in to the Jmix account.

    The Jmix project tree should appear in the Jmix Tool Window.

If the project has been opened for the first time, open File → Project Structure from the main menu.

new project structure

  • Make sure that the Project SDK field has a value corresponding to JAVA_HOME which is set in your environment. If you see the <No SDK> value, select Add SDK from the list and select the folder where the JDK is installed, for example, C:\Program Files\BellSoft\LibericaJDK-17 on Windows or /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home on macOS.

  • Make sure that the Project language level field has a value corresponding to the JDK version. For example, if the JDK is 17, the language level must be 17 - Sealed types, always-strict floating-point semantics.

Also, you can open a project from recent projects. You can do it in the welcome window of the IDE or open File → Open Recent from the main menu.

Upgrading Project

This section covers the process of upgrading a project to a newer Jmix version.

We recommend putting your project under version control and committing all pending changes before the upgrade. It will allow you to see what changes are performed and quickly roll back to a previous version if the upgrade fails for some reason.

  1. Open the project as described in the previous section.

  2. In the Jmix Tool Window, click the Settings button and select Project Properties.

    upgrade tool window

  3. In the Jmix Project Properties dialog, click the Change​ link next to the platform version.

    upgrade properties

  4. In the appeared dialog, choose the desired Jmix version from the drop-down list.

    For the purpose of beta-testing or early accessing new Jmix platform features, you might want to use one of the unstable Jmix platform versions that end with SNAPSHOT, BETA, or RC suffixes. To see them in the platform version drop-down list, you need to select the Show unstable versions checkbox.

    upgrade unstable

    SNAPSHOT, BETA and RC versions are strongly not recommended for use in production.

  5. You can press the Release Notes link and navigate to the documentation page that describes new features, improvements and breaking changes in the API of the new platform version.

    upgrade release notes

  6. If you are upgrading to a newer feature release, for example, from 1.0.X to 1.1.X, the Migration Required section appears.

    upgrade migration required

    By clicking the More info​ link, you can open another dialog containing information about changes that Studio will automatically perform to the project.

    upgrade more info

  7. Click OK to confirm platform version upgrade, and click OK in the Project Properties dialog. Studio will show the migration dialog.

    upgrade migrate

  8. Click Migrate. Studio performs automatic migration and runs Gradle clean task.

  9. If you are upgrading to a feature release, review Breaking Changes section in Release Notes and make changes in your project accordingly.

  10. Assemble your project by executing Jmix Tool Window → Gradle → Assemble.

    upgrade assemble

    Watch the output and fix your code if it doesn’t compile.

Starting Application

When Studio imports Jmix project, it creates Run/Debug Configuration. You can use buttons in the main toolbar to run and stop your application.

To run the application and connect to it with the debugger, just click the debug button next to the selected Jmix Application configuration.

run button

See the status in the Console tab of the Debug tool window.

run link

You can access the application by clicking the link in the console.

To stop the application server, click the button in the main toolbar or in the Debug tool window.

Run/Debug Configuration Settings

You can adjust settings of the application running from the IDE by editing the Jmix Application Run/Debug configuration.

You can open the settings dialog by clicking the Jmix Application element in the toolbar and choose Edit Configurations in the context menu.

run conf

Also, you can open it from the main menu: Run → Edit Configurations.

The Run/Debug Configurations dialog appears.

run dialog

You might be interested in editing the following settings:

  • Before launch - tasks to be performed before starting the application. The following tasks are set automatically for a Jmix project:

    • Clean Hot Deploy Conf Directory - cleaning up hot deploy files created in a previous session.

    • Check Jmix Database - checking the difference between the data model and database schema and generation of database migration scripts. Remove this task if you don’t want to check and generate Liquibase changelogs on each application startup (you can do it manually from the data store context menu).

  • Environment variables – environment variables that should be available to the Gradle process and to the application.

  • VM options – JVM options passed to the Gradle process.

    Note that VM options set in this field do not affect the running application directly. In order to pass them to the application JVM, configure the bootRun task in your build.gradle as follows:

    bootRun {
    if (System.getProperty('jvmArgs')) {
        jvmArgs = (System.getProperty('jvmArgs').split("\\s+") as List)
    }
}

    Then you can set the application JVM options in the VM options field, for example:

    -DjvmArgs="-Duser.timezone=Europe/London -Dsome.property=somevalue"

Using Non-Default JDK

Both IntelliJ IDEA and Gradle by default use Java Development Kit (JDK) defined by the JAVA_HOME environment variable to assemble and run Java projects.

To use a non-default JDK in your project without touching global system settings, do the following:

  1. Open File → Project Structure from the main menu.

  2. Select the desired JDK in the Project → SDK field.

  3. Navigate to the project root folder and create gradle.properties file with the following text:

    # Path to JDK installation folder
org.gradle.java.home = /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home

  4. In the Gradle tool window click Reload All Gradle Projects to refresh the Gradle project configuration.

Hot Deploy

See Hot Deploy section for more details.