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

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

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

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:\Java\jdk8u202-b08 на Windows или /Library/Java/JavaVirtualMachines/jdk8u202-b08/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 в окне Jmix Tool Window.

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

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

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

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

    new project welcome

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

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

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

    new project open

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

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

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

  • Убедитесь, что в поле Project language level стоит значение, соответствующее версии JDK. Например, если версия JDK 1.8, уровень языка должен быть 8 - Lambdas, type annotations, etc.

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

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

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

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

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

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

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

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

    upgrade change

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

    upgrade unstable

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

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

    upgrade release notes
  6. При апгрейде до более нового функционального релиза, например, с 1.0.X до 1.1.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

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

  11. Разверните Data Stores в окне инструментов Jmix и выберите Generate Liquibase Changelog в контекстном меню хранилищ данных.

    upgrade changelog

    Возможные изменения схемы фреймворка будут внесены в базу данных вашего проекта.

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

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

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

run button

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

run link

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

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

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

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

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

  • 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

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

Давайте предположим, что переменная окружения JAVA_HOME указывает на JDK 8, а вы хотите использовать JDK 11 в своем проекте.

Вам необходимо выполнить следующие действия:

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

  2. Выберите SDKs в левом меню. Нажмите кнопку + и выберите Add JDK.

    jdk add
  3. Выберите папку установки JDK 11. Нажмите OK, чтобы сохранить изменения.

  4. Если вы создаете новый проект Jmix, введите "11" в поле Project SDK.

    Для уже существующих проектов откройте File → Project Structure в главном меню и измените значение Project → Project SDK.

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

    # Path to JDK 11
    org.gradle.java.home = C:/Java/jdk-11.0.5.10-hotspot
  6. Измените файл build.gradle, расположенный в корневой папке проекта, добавив следующие инструкции:

    group = '...'
    version = '...'
    sourceCompatibility = '11'
    targetCompatibility = '11'
  7. В окне инструмента Gradle нажмите Reload All Gradle Projects, чтобы обновить конфигурацию проекта Gradle.

Когда эти изменения будут выполнены, проект будет скомпилирован и запущен с JDK 11 без изменения глобальных системных настроек.

Hot Deploy

Для получения дополнительной информации см. раздел Hot Deploy.