Работа с проектом

В этом разделе описывается, как создать новый проект, открыть существующий и запустить приложение.

Создание нового проекта

Studio предоставляет мастера настройки для создания новых проектов Jmix с нуля.

  1. Откройте мастер New Project из главного меню: File → New → Project. Вы также можете нажать New Project на приветственном экране IDE.

  2. Выберите Jmix Project в диалоговом окне.

    new project create

    На этом этапе, настройте основные параметры проекта:

    • Вы можете принять репозиторий по умолчанию, указанный в поле Repository, или нажать Custom repository и выбрать свой.

    • Выберите Use local Maven repository если вы хотите использовать артефакты из локального репозитория.

    • В Jmix version выберите нужную для проекта версию Jmix. Если у вас нет каких-либо особых требований, используйте последнюю выпущенную версию.

      Для бета-тестирования или раннего доступа к новым функциям фреймворка Jmix вы можете использовать одну из нестабильных версий, названия которых заканчиваются суффиксами BETA или SNAPSHOT. Чтобы увидеть их в выпадающем списке Jmix version, поставьте флажок Show unstable versions.

    • В поле Project JDK, выберите JDK, соответствующий переменной JAVA_HOME, заданной в вашем окружении. Если вы видите значение <No JDK>, нажмите Add JDK в списке и выберите папку, в которую установлен JDK, например C:\Program Files\BellSoft\LibericaJDK-17 на Windows или /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home на macOS.

  3. На следующем шаге мастера выберите шаблон, который будет использоваться для создания пустого проекта.

    new project templates

  4. В следующем окне задайте название, местоположение и локализацию проекта.

    new project name

    • При необходимости измените значение поля Project name. Имя проекта должно содержать только латинские буквы, цифры и подчеркивания.

    • Project location – это путь к новому каталогу проекта. Вы можете выбрать другой каталог, введя его в поле или нажав кнопку рядом с полем.

    • Base package – это базовый пакет для классов и ресурсов Java. Тщательно выбирайте название пакета. Позже вы сможете изменить имя и переместить классы и ресурсы только вручную.

    • Project id опционален. Если он установлен, Studio будет использовать его в качестве префикса для имен сущностей, таблиц и бинов. Идентификатор проекта не должен быть длиннее 7 символов.

    • Используйте поле Locales, чтобы открыть редактор и добавить в проект дополнительные поддерживаемые локали. Вы сможете изменить их позже, если потребуется.

  5. Нажмите Finish. Пустой проект будет создан в указанном каталоге, и Studio начнет собирать информацию о проекте из файлов Gradle и индексировать проект.

    Если вы впервые начинаете работать с проектом в Jmix Studio, вам следует войти в учетную запись Jmix.

    Когда процесс синхронизации и индексирования проекта будет завершен, вы увидите дерево проекта Jmix в окне Jmix Tool Window.

Теперь вы можете приступить к работе над проектом.

Открытие существующего проекта

Чтобы открыть проект, выполните следующие действия:

  1. Нажмите Open на приветственном экране IDE.

    new project welcome

    Если уже открыт другой проект, перейдите в главное меню File → Open.

  2. В диалоговом окне файловой системы выберите корневую папку проекта, содержащую файл build.gradle, выберите его и нажмите OK.

    new project build

    При открытии композитного проекта убедитесь, что вы перешли в директорию проекта-агрегатора <project-name>-all и открыли файл build.gradle в этой директории:

    open composite project

  3. В появившемся окне выберите Open as Project.

    new project open

    Дождитесь завершения синхронизации Gradle и индексирования проекта.

    Если вы впервые начинаете работать с проектом в Jmix Studio, вам следует войти в учетную запись Jmix.

    Дерево проекта Jmix должно появиться в окне Jmix Tool Window.

Если проект был открыт в первый раз, перейдите в File → Project Structure из главного меню.

new project structure

  • Убедитесь, что в поле Project SDK стоит значение, соответствующее переменной JAVA_HOME, заданной в вашем окружении. Если вы видите значение <No JDK>, нажмите Add JDK в списке и выберите папку, в которую установлен JDK, например C:\Program Files\BellSoft\LibericaJDK-17 на Windows или /Library/Java/JavaVirtualMachines/liberica-jdk-17.jdk/Contents/Home на macOS.

  • Убедитесь, что в поле Project language level стоит значение, соответствующее версии JDK. Например, если версия JDK 17, уровень языка должен быть 11 - Sealed types, always-strict floating-point semantics.

Также вы можете открыть один из последних проектов. Вы можете сделать это в окне приветствия IDE или выбрать File → Open Recent в главном меню.

Апгрейд проекта

В этом разделе описывается процесс обновления проекта до более новой версии Jmix.

Мы рекомендуем использовать систему контроля версий в вашем проекте и закоммитить все незавершенные изменения перед обновлением. Это позволит вам увидеть, какие изменения будут внесены, и быстро вернуться к предыдущей версии, если обновление по какой-либо причине завершится неудачно.

  1. Откройте проект, как описано в предыдущем разделе.

  2. В окне инструментов Jmix нажмите кнопку Settings и выберите Project Properties.

    upgrade tool window

  3. В диалоговом окне Jmix Project Properties перейдите по ссылке Change рядом с версией фреймворка.

    upgrade properties

  4. В появившемся диалоговом окне выберите нужную версию Jmix из выпадающего списка.

    В целях бета-тестирования или раннего доступа к новым функциям фреймворка Jmix вы можете использовать одну из нестабильных версий, названия которых заканчиваются суффиксами SNAPSHOT, BETA или RC. Чтобы увидеть их в выпадающем списке, поставьте флажок Show unstable versions.

    upgrade unstable

    SNAPSHOT, BETA и RC версии настоятельно не рекомендуются для использования в проектах, находящихся в эксплуатации.

  5. Нажав на ссылку Release Notes вы перейдете к странице документации, на которой описаны новые функции, улучшения и критические изменения в API новой версии фреймворка.

    upgrade release notes

  6. При апгрейде до более нового функционального релиза, например, с 2.3.X до 2.4.X, появится раздел Migration Required.

    upgrade migration required

    Нажав на ссылку More info, вы откроете диалоговое окно, содержащее информацию об изменениях, которые Studio автоматически внесет в проект.

    upgrade more info

  7. Нажмите OK, чтобы подтвердить обновление версии фреймворка, и нажмите OK в окне Project Properties. Studio откроет диалоговое окно миграции.

    upgrade migrate

  8. Нажмите Migrate. Studio проведет автоматическую миграцию и выполнит задачу Gradle clean.

  9. Если вы обновляетесь до функционального релиза, просмотрите Breaking Changes в разделе Что нового и внесите соответствующие изменения в проект.

  10. Соберите проект, выполнив Jmix Tool Window → Gradle → Assemble.

    upgrade assemble

    Проследите за выводом в консоли и исправьте код, если он не компилируется.

Запуск приложения

Когда Studio импортирует проект Jmix, она создает конфигурацию Jmix Run/Debug. Вы можете использовать кнопки на главной панели инструментов для запуска и остановки приложения.

Чтобы запустить приложение и подключить к нему отладчика, просто нажмите кнопку отладки рядом с выбранной конфигурацией Jmix Application.

run button

Следите за статусом на вкладке Console окна инструментов Debug.

run link

Через некоторое время вы сможете войти в приложение, кликнув на ссылку в консоли.

Чтобы остановить сервер приложения, кликните кнопку на главной панели инструментов или в окне инструментов Debug.

Окно предварительного просмотра changelog

Перед запуском приложения Studio проверяет различия между моделью данных проекта и схемой базы данных. Если вы создали новую сущность, Studio автоматически генерирует changelog Liquibase для соответствующих изменений в базе данных:

changelog preview window

Каждый changelog получает уникальное имя файла, которое Studio создаёт автоматически. Вы можете изменить это имя в поле File name.

В левой части окна отображается предпросмотр изменений (changesets), которые будут созданы. При клике на любой changeset в списке откроется детальное описание его содержимого. В верхнем левом углу предпросмотра находится панель инструментов с действиями для редактирования changelog.

changelog preview window actions

Доступны следующие действия:

  • Remove from Changelog предлагает следующие варианты:

    • Remove from Changelog: просто удаляет выбранные изменения из текущего changelog.

    • Remove and Ignore: удаляет изменения и добавляет их в список "Ignored", чтобы они не появлялись в будущих changelog.

  • Restore from Ignored: переносит изменения из списка "Ignored" обратно в changelog.

  • Show Other Actions: позволяет выбрать изменения по уровню опасности, а также развернуть или свернуть все изменения.

Чтобы сохранить сгенерированный changelog и запустить приложение, нажмите кнопку Save and run.

Если нужно пропустить сохранение changelog и просто запустить приложение, используйте кнопку Discard and run.

Настройка конфигурации Run/Debug

Конфигурация запуска/отладки Jmix автоматически создается при открытии проекта Jmix в IDE. Эта конфигурация упрощает процесс запуска и отладки вашего приложения Jmix непосредственно из IDE. Конфигурация запуска/отладки также создается, если щелкнуть правой кнопкой мыши по корневому узлу вашего проекта Jmix в окне инструментов Jmix и выбрать Start Application в контекстном меню.

Вы можете настроить параметры приложения, запускаемого из IDE, отредактировав конфигурацию запуска/отладки Jmix.

Чтобы получить доступ к настройкам и изменить конфигурацию запуска/отладки, щелкните элемент Jmix Application на панели инструментов и выберите Edit Configurations в контекстном меню.

run conf

Также вы можете открыть его из главного меню: Run → Edit Configurations.

Откроется диалоговое окно настройки Run/Debug Configurations.

run dialog

Возможно, вам будет интересно отредактировать следующие настройки:

  • Before launch - задачи, выполняемые перед стартом приложения. Следующие задачи относятся к проектам на Jmix:

    • Clean Hot Deploy Conf Directory - очистка hot deploy файлов, созданных в предыдущих сеансах запуска.

    • Check Liquibase Changelog Includes - проверяет, соответствуют ли включения в корневом файле changelog дополнениям, используемым в проекте. Если есть несоответствие, Studio показывает диалоговое окно уведомления и предлагает добавить или удалить включения.

    • Check Jmix Database - проверка соответствия модели данных и схемы БД и создание скриптов миграции базы данных. Удалите эту задачу, если вы не хотите проверять и генерировать Liquibase changelogs при каждом запуске приложения (вы можете сделать это вручную через контекстное меню хранилища данных).

    • Assemble - создает выходные артефакты вашего проекта, не запуская тесты.

  • Environment variables – переменные окружения, которые должны быть доступны процессу Gradle и приложению.

  • VM options – параметры JVM, передаваемые процессу Gradle.

    Параметры VM, указанные в данном поле, не влияют напрямую на запускаемое приложение. Чтобы передать их в JVM приложения, сконфигурируйте задачу bootRun в build.gradle следующим образом:

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

    После этого вы можете передать параметры JVM приложения из поля VM options, например:

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

Использование нестандартного JDK

Как IDE, так и Gradle по умолчанию используют Java Development Kit (JDK), определенный переменной окружения JAVA_HOME, для сборки и запуска проектов Java.

Чтобы использовать нестандартный JDK в своем проекте, не затрагивая глобальные системные настройки, вам необходимо выполните следующее:

  1. Откройте File → Project Structure из главного меню IDE.

  2. Выберите желаемый в поле Project → SDK.

  3. Перейдите в корневой каталог проекта и создайте файл gradle.properties следующего содержания:

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

  4. В окне инструмента Gradle нажмите Reload All Gradle Projects, чтобы обновить конфигурацию проекта Gradle.

Устранение неполадок

Если вы столкнулись с какими-либо проблемами во время работы над проектом, попробуйте закрыть его и открыть снова. Если это не помогло, попробуйте сбросить кэши и перезапустить IDE:

  1. Выберите пункт File → Invalidate Caches в главном меню.

  2. Включите флажок Delete Jmix Studio templates and artifacts caches.

  3. Нажмите Invalidate and Restart.

Обратите внимание, что при последующем открытии проекта переиндексация зависимостей может занять некоторое время.