Введение

Данное руководство содержит справочную информацию о среде разработки CUBA Studio и её возможностях, помогающих ускорить разработку приложений на платформе.

CUBA Studio основана на платформе IntelliJ IDEA Platform с открытым исходным кодом и дополняет её функциональность следующими возможностями, специфичными для платформы:

  • Автоматическая генерация скриптов сборки Gradle.

  • Генерация модели данных, схемы БД и CRUD UI.

  • Визуальный WYSIWYG-дизайнер компоновки экрана.

  • Удобные приёмы и функции интерфейса, которые упрощают и ускоряют процесс кодирования: действия (actions), подсказки (intentions), проверки (inspections), внутренние ссылки (references).

  • Простые средства для интернационализации приложений.

  • Создание модели данных и экранов UI поверх существующей (legacy) базы данных.

  • Hot (re)deploy - мгновенное отображение сделанных в проекте изменений в работающем приложении без необходимости перезапускать сервер.

  • Удобная миграция на более новые версии платформы и дополнений (Add-ons).

Release Notes

Версия 9
  1. BREAKING CHANGE: Studio теперь включает HSQL версии 2.4.1. При первом открытии проекта, использующего базу данных HSQL, Studio предлагает обновить версию HSQL в файле build.gradle проекта. После обновления, проект будет корректно работать в Studio версии 9+. Однако, имейте в виду следующие возможные проблемы:

    1. Приложение не сможет стартовать, если проект с новым драйвером HSQL будет открыт в предыдущей версии Studio, содержащей старый сервер HSQL;

    2. В проектах с HSQL на базе CUBA версии ниже 7.1, Scheduled Tasks не работают, так как их таблица содержит колонку с именем PERIOD, которое является зарезервированным словом в HSQL 2.4.1. Колонка переименована в CUBA 7.1.

  2. Механизм Hot deploy теперь деплоит все зависимые классы вместе с измененным, что исключает ClassCastException при открытии измененных экранов.

  3. При выборе базы данных MySQL или Oracle, Studio отображает диалог, из которого можно перейти по ссылке на сайт поставщика для загрузки драйвера, а затем загрузить его из локальной файловой системы в нужный каталог проекта в саму Studio. После загрузки драйвера перезапустите Studio.

    Драйверы могут быть удалены из Studio с помощью страницы настроек CUBA > Database Proprietary Drivers.

  4. Для шаблонов browser и master-detail мастера Create CUBA Screen можно выбрать компоненты DataGrid или TreeDataGrid.

  5. В мастер Create CUBA Screen добавлены шаблоны Extend an existing screen и Entity fragment.

  6. Действия Undo/Redo теперь корректно работают в дизайнере экранов.

  7. Реализовано автодополнение для запросов загрузчиков данных в дизайнере экранов.

  8. В дизайнер экранов добавлена кнопка для быстрого переключения на контроллер, см. верхний правый угол холста.

  9. Добавлены предупреждения об использовании атрибутов invoke и datasource в экранах основанных на новом API.

  10. Если поддержка Groovy выбрана в окне Project Properties, Groovy может быть выбран в поле Advanced > Controller language мастера Create CUBA Screen.

  11. Сервисы, написанные на Groovy, отображаются в дереве проекта CUBA.

  12. Добавлено оповещение о доступности новых версий платформы при открытии проекта.

  13. Улучшены gutter icons в редакторе исходного кода.

  14. Тип атрибута сущности может быть произвольно изменен в дизайнере сущности с запуском рефакторинга или без него.

  15. Реализован дизайнер Enumeration.

  16. Дизайнер представлений переписан на нативный IntelliJ UI.

  17. Генератор модели данных теперь содержит шаблоны экранов с новым API.

  18. Все завершенные задачи:

Версия 8
  1. Первое открытие проекта теперь выполняется с помощью мастера импорта проектов. См. Открытие существующего проекта для подробной информации.

  2. Модель проекта теперь сохраняется в файле внутри каталога .idea проекта, поэтому синхронизация Gradle не запускается каждый раз при открытии проекта.

  3. Редактор Run/Debug Configuration теперь позволяет выбрать JDK, который должен использоваться для запуска сервера приложения: см. поле JVM на вкладке Configuration. По умолчанию используется значение переменной окружения JAVA_HOME.

  4. Представления (views) можно переименовывать с помощью стандартного действия Refactor > Rename. Это действие можно вызвать в дереве проекта CUBA, на атрибуте name XML-элемента view в файле views.xml, а также на любой ссылке на представление в XML-дескрипторах экранов.

  5. Редактор представления можно вызвать из поля view контейнера данных в дизайнере экрана.

  6. Реализовано автодополнение и поиск ссылок для атрибута screen XML-элемента <fragment> в дескрипторах экранов.

  7. Реализован редактор локализованных сообщений для заголовков меню. Щелкните Generic UI > Web Menu в дереве проекта CUBA, переключитесь на вкладку Structure, выберите пункт меню и нажмите edit в поле Caption.

  8. Реализовано предупреждение для значений перечислений, не имеющих локализованных заголовков. Если вы увидели предупреждение, используйте quick fix Create message in the message bundle для создания заголовка по умолчанию.

  9. Реализовано автодополнение для имен свойств приложения, декларированных в конфигурационных интерфейсах. Нажмите Ctrl+Space при задании свойства в файлах app.properties или web-app.properties.

  10. Все завершенные задачи:

Версия 7
  1. Если ваш проект базируется на CUBA 6.10 и использует премиум-дополнения BPM, Charts, Full-Text Search или Reports, необходимо установить имя и пароль доступа к репозиторию в файле ~/.gradle/gradle.properties, как описано в Руководстве по разработке приложений. Studio не передает имя и пароль доступа к репозиторию в Gradle.

  2. Все завершенные задачи:

1. Установка

Перед установкой CUBA Studio убедитесь, что на вашей рабочей машине установлено и настроено необходимое программное обеспечение, описанное в разделе Установка и настройка основного Руководства по разработке.

CUBA Studio можно установить в двух различных формах: как отдельную IDE для вашей операционной системы, или как плагин для имеющейся IntelliJ IDEA. Отдельная IDE представляет собой специальную сборку IntelliJ IDEA Community Edition, включающую в себя плагин CUBA. Если вы ранее не использовали IntelliJ IDEA, мы рекомендуем установить Studio как отдельную IDE.

IDE имеет версию, соответствующую используемой версии IntelliJ IDEA, например 2018.3. Плагин CUBA имеет свою собственную версию, начинающуюся с 9.

Установочные файлы IDE для Windows, macOS и Linux доступны по адресу https://www.cuba-platform.com/download. Плагин доступен в репозитории плагинов IntelliJ (см. ниже).

Установка на Windows
  1. Скачайте программу установки cuba-studio-VERSION.exe.

  2. Запустите программу установки и следуйте инструкциям в появившемся окне: выберите путь к каталогу установки, тип загрузчика, имя каталога, после чего дождитесь завершения установки.

  3. Запустите установленное приложение и см. ниже для дальнейших инструкций.

Установка на macOS
  1. Скачайте программу установки cuba-studio-VERSION.dmg.

  2. Дважды щёлкните на программы установки, затем перетащите файл CUBA Studio.app в каталог Applications. Если на вашем компьютере установлена более старая версия Studio, которую вы хотели бы сохранить, выберите Keep Both в появившемся диалоговом окне.

  3. Запустите приложение CUBA Studio и см. ниже для дальнейших инструкций.

Установка на Linux
  1. Установите необходимые зависимости:

    $ sudo apt-get install libgconf-2-4
  2. Скачайте архив cuba-studio-VERSION.tar.gz.

  3. Перенесите архив в подходящий каталог, например, ~/lib, и распакуйте его:

    $ tar -xvf cuba-studio-VERSION.tar.gz
  4. Перейдите в подкаталог bin и запустите приложение:

    $ cd ~/lib/cuba-studio-VERSION/bin
    $ ./cuba-studio.sh
Первый запуск IDE

При первом запуске CUBA Studio IDE вам необходимо ответить на несколько вопросов:

  • В первом диалоге Complete Installation, выберите Do not import settings и нажмите OK.

  • В следующем диалоге Customize CUBA Studio, щелкните Skip Remaining and Set Defaults чтобы применить параметры по умолчанию. Вы сможете изменить их в любое время позже.

  • Далее см. раздел Приступая к работе для информации о том как создать новый или открыть существующий проект.

Установка плагина для IntelliJ IDEA
  1. Запустите IntelliJ IDEA 2018.3 или более новую версию.

  2. Откройте диалог Plugins.

  3. Щелкните на значок "шестеренка" и выберите Manage Plugin Repositories.

  4. Щелкните Add и введите в поле Repository URL следующее значение:

    https://plugins.jetbrains.com/plugins/haulmont/list
  5. После добавления репозитория, переключитесь на вкладку Marketplace.

  6. Введите следующее значение в поле поиска:

    repository:"https://plugins.jetbrains.com/plugins/haulmont/list"
  7. Вы увидите плагин CUBA в результатах поиска.

  8. Нажмите Install и следуйте инструкциям IDE.

2. Обновление

Обновление IDE

Вы можете просто загрузить новую версию Studio IDE с веб-сайта и установить ее поверх имеющейся версии. Все настройки будут сохранены.

Вместо загрузки и инсталляции IDE целиком, можно настроить автоматическое обновление плагина CUBA из репозитория плагинов:

  1. Откройте диалог Plugins.

  2. Щелкните на значок "шестеренка" и выберите Manage Plugin Repositories.

  3. Щелкните Add и введите в поле Repository URL следующее значение:

    https://plugins.jetbrains.com/plugins/haulmont/list
  4. После добавления репозитория, переключитесь на вкладку Updates.

  5. Если есть доступные обновления, вы увидите их в списке. Нажмите Update для плагина CUBA, и IDE загрузит новую версию.

  6. После завершения процесса загрузки необходимо рестартовать IDE для применения новой версии плагина.

Обновление плагина в IntelliJ IDEA
  1. Выберите Help > Check for Update на Windows и Linux, или IntelliJ IDEA > Check for Updates на macOS.

  2. Если есть доступные обновления, вы увидите их в списке. Выберите плагин CUBA и нажмите Update. IDE загрузит новую версию.

  3. После завершения процесса загрузки необходимо рестартовать IDE для применения новой версии плагина.

3. Приступая к работе

В данном разделе описано, как создавать новые и открывать существующие проекты в Studio и с чего начать работу над приложением.

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

С помощью CUBA Studio легко создавать приложения на платформе с нуля. Запустите мастер New Project и выполняйте шаги, описанные ниже:

  1. В окне Welcome to CUBA Studio выберите Create New Project.

  2. Выберите CUBA Project.

  3. В поле Project SDK выберите JDK, соответствующий переменной окружения JAVA_HOME, установленной в вашей операционной системе. Если вы видите значение <No SDK>, то нажмите New и выберите каталог установки нужного JDK, например C:\Java\jdk8u202-b08 на Windows или /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home на macOS.

  4. Вы можете принять настройки доступа к репозиториям платформы по умолчанию или изменить их для конкретного проекта. Затем нажмите Next.

  5. Введите имя нового проекта в поле Project name. Имя должно содержать только латинские буквы, цифры и знак подчеркивания. Тщательно продумайте имя проекта на данном этапе, так как в дальнейшем изменить его будет достаточно сложно.

  6. В полях ниже автоматически сгенерируются:

    • Project location – путь к каталогу нового проекта. Путь можно изменить, введя адрес каталога вручную или нажав на кнопку с многоточием рядом с полем.

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

    • Root package − корневой (или основной) пакет Java-классов проекта. Может быть скорректирован позже, однако сгенерированные на этапе создания классы перемещены не будут.

    • Platform version – используемая в проекте версия платформы. Если у вас нет особых требований, выбирайте последнюю релизную версию, т.е. с номером без суффиксов BETA или SNAPSHOT. Артефакты платформы будут автоматически загружены из репозитория при сборке проекта.

  7. Нажмите Finish. В указанном каталоге будет создан пустой проект, и в главном окне Studio начнётся сборка проекта по скриптам Gradle и индексирование файлов проекта.

  8. После окончания процессов синхронизации и индексации вы увидите дерево проекта CUBA в боковой панели Project.

  9. Откройте боковую панель Gradle, которая по умолчанию находится справа. Щелкните по значку "гаечный ключ" (Gradle Settings) и выберите Use JAVA_HOME в поле Gradle JVM. Если вы не видите такого пункта в выпадающем списке, убедитесь, что вы правильно настроили окружение согласно инструкции в разделе Установка и настройка руководства по разработке приложений. Нажмите OK.

  10. Теперь можно начинать работу с проектом.

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

Открытие уже импортированного проекта

Если проект ранее уже был открыт в CUBA Studio на данном компьютере, достаточно сделать следующее:

  1. Используйте список недавних проектов; или нажмите Open, выберите папку проекта в диалоговом окне файловой системы и нажмите на кнопку Open.

  2. Дождитесь завершения синхронизации Gradle и индексации файлов проекта. Когда откроется дерево проекта CUBA в окне инструментов Project, можно начинать работу с проектом.

Первое открытие проекта

Если проект ранее не был открыт в CUBA Studio на данном компьютере (например, вы только что импортировали его из VCS), необходимо сделать следующее:

  1. В окне Welcome нажмите Import Project. Если какой-либо проект уже открыт, то выберите File > New > Project from Existing Sources в главном меню.

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

  3. В окне Import Project выберите переключатель Import project from external model и пункт CUBA в списке ниже, затем нажмите Next.

  4. На следующей странице мастера импорта просто нажмите Finish.

  5. Дождитесь завершения синхронизации Gradle и индексации файлов проекта. В окне инструментов Project должно появиться дерево проекта CUBA.

  6. Выберите File > Project Structure в главном меню.

    • Убедитесь, что поле Project SDK имеет значение, соответствующее переменной окружения JAVA_HOME установленной в вашей операционной системе. Если вы видите значение <No SDK>, то нажмите New и выберите каталог установки нужного 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.

Первое открытие проекта на платформе CUBA версии 6.10

CUBA Studio поддерживает работу с проектами, использующими версии платформы 6.10+ и 7.0. Вы можете открыть проект, созданный в предыдущей версии Studio, и импортировать его в новую Studio.

Имейте в виду, что CUBA 6 поддерживает только Java 8, поэтому ваша переменная JAVA_HOME должна указывать на каталог установки JDK 8. Позже, после миграции на CUBA 7, вы сможете выбрать более новый JDK, если это необходимо.

Выполните следующие шаги для первого открытия проекта, использующего CUBA 6.10:

  1. Если ваш проект использует премиум-дополнения (Reports, BPM, etc.) и у вас есть подписка, необходимо прописать имя и пароль доступа к репозиторию в файле ~/.gradle/gradle.properties как описано в документации.

  2. Удалите старые файлы IntelliJ с помощью задачи gradlew cleanIdea в командной строке.

  3. Если проект находится под управлением Git, добавьте строку .idea в файл .gitignore, расположенный в корневом каталоге проекта. Так вы избежите попадания локальных настроек IDE в рабочую среду других разработчиков вашего проекта.

  4. Импортируйте проект как описано выше в секции Первое открытие проекта.

3.3. Обновление проекта

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

Tip

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

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

  • Выберите CUBA > Project Properties в основном меню либо дважды нажмите на Project > Properties в дереве проекта CUBA.

  • В открывшемся окне CUBA Project Properties выберите желаемую версию платформы в поле Platform version.

    Warning

    Если вы используете репозиторий repo.cuba-platform.com, вам будут доступны SNAPSHOT-версии платформы. Мы категорически не рекомендуем использовать эти версии в промышленной эксплуатации.

  • Нажмите OK, затем подтвердите изменения.

  • Если вы обновляетесь до нового feature release (к примеру, с 6.10.X до 7.0.X или с 7.0.Y до 7.1.Y), появится диалоговое окно Migration Required. В этом окне содержится информация об этапах миграции, которые Studio выполнит автоматически. Ознакомьтесь с этой информацией и нажмите Migrate.

  • Studio выполнит автоматическую миграцию (при необходимости) и выполнит задачи Gradle clean и undeploy.

  • Если вы обнрвляетесь до нового feature release, просмотрите раздел Breaking Changes в Release Notes и при необходимости внесите соответствующие изменения в ваш проект.

  • Попробуйте собрать проект, выполнив команду CUBA > Build Tasks > Assemble. Просмотрите журнал вывода и поправьте код, если в логах есть сообщения об ошибках компиляции.

  • Выполните команду CUBA > Update Database, чтобы применить возможные изменения в системных таблицах платформы к базе данных вашего проекта.

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

Когда Studio импортирует проект CUBA-приложения, автоматически создается Run/Debug Configuration, предназначенная для запуска локального сервера Tomcat. Поэтому для того, чтобы запустить приложение и подключиться к нему отладчиком, достаточно кликнуть на кнопку "debug" рядом с выбранной конфигурацией CUBA Application в главной панели инструментов:

app start 1

Статус запуска отображается во вкладке Console окна инструментов Debug. Для того, чтобы открыть UI приложения в браузере, щелкните по ссылке, выведенной в сообщении Server started at.

app start 2

Вы также можете открыть запущенное приложение в браузере, используя элемент дерева CUBA Runs At…​:

runs at

Для того, чтобы увидеть вывод сервера, переключитесь на вкладку catalina.out:

app start 3

Остановить сервер можно, выбрав команду Run > Stop 'CUBA Application' главного меню, или щелкнув по кнопке в окне инструментов Debug:

app start 4

Рекомендуемый способ запуска приложения при разработке - описанное выше использование Run/Debug Configuration, однако вы также можете управлять локальным сервером Tomcat с помощью команд меню CUBA:

cuba menu 2

При запуске сервера командой Start Application Server, в Windows вы увидите консольное окно с выводом сервера. В Linux и macOS консоль не отображается, однако логи сервера можно увидеть, выполнив tail -f deploy/tomcat/logs/app.log в окне инструментов Terminal. Команда Stop Application Server останавливает сервер Tomcat, посылая сигнал SHUTDOWN на shutdown port, указанный в свойствах проекта (8005 по умолчанию).

4. Пользовательский интерфейс Studio

В данном разделе описываются элементы пользовательского интерфейса IDE, специфичные для платформы CUBA. Для знакомства с остальными особенностями IntelliJ IDEA рекомендуем обратиться к её документации.

4.1. Дерево проекта CUBA

Дерево проекта CUBA отображает структуру проекта и его важные элементы. По умолчанию оно открывается в окне инструментов Project в левой части IDE. Чтобы переключиться на представление в виде дерева, выполните команду CUBA > Project Tree в главном меню или выберите вариант CUBA в выпадающем списке в верхней части окна инструментов Project.

Дерево проекта содержит следующие элементы:

cuba tree
CUBA
    Application
            http://localhost:8080/app
    Project
        Properties
        Build Script
            build.gradle
            settings.gradle
        Modules
            global
                metadata.xml
                persistence.xml
                views.xml
            core
                app.properties
                spring.xml
            web
                web-app.properties
                web-dispatcher-spring.xml
                web-menu.xml
                web-permissions.xml
                web-screens.xml
                web-spring.xml
        Data Stores
            _MAIN_
        Deployment
            WAR Settings
            UberJAR Settings
    Data Model
    Middleware
        Services
        Beans
    Generic UI
        Web menu
        Main Message Pack
            messages.properties
        Screens
        Themes
    REST API
  1. Project

    • Properties - позволяет настроить основные параметры проекта.

    • Build Script - содержит два основных скрипта проекта: build.gradle (определяет конфигурацию сборки) и settings.gradle (задаёт имя проекта и набор модулей).

    • Modules - отображает все модули проекта.

    • Data Stores - отображает список data stores (хранилищ данных), к которым подключен проект. По умолчанию здесь отображается единственное хранилище MAIN.

    • Deployment - позволяет настроить варианты развёртывания проекта.

  2. Data model - отображает модель данных проекта.

  3. Middleware - отображает сервисы и управляемые бины.

  4. Generic UI - включает в себя всё, что относится к пользовательскому интерфейсу проекта: экраны, темы и т.д.

  5. REST API - позволяет настроить функциональность REST API.

  6. Runs At…​ - позволяет открыть запущенное приложение во внешнем или встроенном веб-браузере.

Используйте контекстное меню, открывающееся по щелчку правой кнопки мыши на элементах дерева, чтобы выполнять действия, которые относятся к этим элементам. К примеру, используя контекстное меню элемента Data Model, вы можете генерировать скрипты создания и обновления БД, создавать новые сущности и перечисления:

cuba tree context menu

4.2. Главное меню CUBA

Главное меню CUBA обеспечивает быстрый доступ к CUBA-специфичной функциональности IDE. Некоторые пункты этого меню дублируют функциональность, доступную в дереве проекта и его контекстном меню.

cuba menu

Наиболее часто используемые элементы меню можно добавить на панель инструментов. Для этого необходимо кликнуть на панель и выбрать Customize Menus and Toolbars. В диалоговом окне Menus and Toolbars разверните элемент Main Toolbar и используйте команду Add Action для добавления команд из дерева Main Menu > CUBA.

4.3. Меню настроек CUBA Settings

При выборе элемента CUBA > Settings в главном меню откроется окно настроек IDE, отфильтрованных по слову cuba. Найдите секцию CUBA под секцией Languages & Frameworks.

В секции CUBA содержатся общие настройки, которые распространяются на все проекты, открываемые в данной установленной Studio.

  • Ask before saving DB scripts with DROP statements - предлагать исключить скрипты обновления БД, содержащие команду DROP, из списка скриптов для автоматического выполнения.

  • Show warning if application server port is in use - показывать предупреждение при открытии проекта, если используемый в нём порт Tomcat в данный момент занят.

  • Use embedded browser to open application - если установлен этот флажок, то при двойном клике на секции дерева Runs At запущенное приложение будет открываться во встроенном веб-браузере.

  • Visual designer theme - тема визуальных дизайнеров. Используйте Autodetect, чтобы тема автоматически подстраивалась под тему, выбранную для IDE.

  • Visual designer zoom - масштаб (zoom) визуальных дизайнеров по умолчанию. Масштаб можно настроить и для каждого дизайнера отдельно, используя контекстное меню, открываемое правым щелчком мыши.

  • Old Studio integration enabled - поставьте этот флажок, если вы хотите интегрировать текущий экземпляр IDE со старой Studio SE или Studio Browser Edition. Так вы сможете открывать проекты из старой Studio в этой IDE.

  • Listening port - порт интеграции со старой Studio. Убедитесь, что этот же порт указан в настройках старой Studio в поле IDE Port.

  • Enable transaction block folding - если установлен этот флажок, редактор кода Java свернёт в старом стиле блоки try-finally, использующиеся для контроля транзакций.

Вложенная секция Project settings содержит настройки IDE для текущего открытого проекта. Все настройки, отличные от настроек по умолчанию, сохраняются в файле studio-intellij.xml в корневом каталоге проекта. Этот файл можно добавить в систему контроля версий, чтобы поделиться настройками с другими разработчиками данного проекта.

  • Check compatibility between data model and database scheme - показывать предупреждение при каждом запуске сервера приложения, если текущее состояние модели данных приложения отличается от текущей схемы базы данных.

  • Generate DROP statements in separate update scripts - генерировать более безопасные скрипты обновления БД при удалении сущности и удалении или изменении типа данных её атрибута. Такие скрипты разделены на две части: в первой части скрипта колонка или вся таблица переименовываются в *__UNUSED, а во второй части эти объекты удаляются по-настоящему.

  • Use NVARCHAR when generating scripts for MS SQL Server - если включена эта опция и выбран тип БД Microsoft SQL Server, то для всех строковых атрибутов будет использоваться тип колонки NVARCHAR.

  • Generate script name in format - укажите yyMMddHHmm, чтобы добавлять текущее время к именам генерируемых скриптов обновления базы данных. Это обеспечит правильную последовательность скриптов при совместной работе над проектом.

  • Do not delete columns started with - в этом поле можно указать префикс для колонок таблицы, которые нужно исключить из отслеживания Studio. Если вы добавляете колонку в таблицу, сопоставленную с некой сущностью, и не совмещаете колонку с атрибутом этой сущности, Studio сгенерирует скрипт обновления БД, удаляющий эту колонку. Чтобы избежать удаления, вы можете исключить этот скрипт в диалоговом окне Database Scripts, и он больше не будет сгенерирован. В качестве альтернативы вы можете указать общий префикс для таких колонок в поле Do not delete columns started with и использовать этот префикс в именах колонок. Например, можно ввести NOT_MAPPED_ в указанном поле и назвать колонку NOT_MAPPED_CODE.

  • Column length for enums with ID of String type - в этом поле можно установить длину колонки в БД, которая соответствует атрибуту сущности с типом enum, имеющим строковый идентификатор. К примеру, если вы хотите использовать короткие идентификаторы, состоящие из одного символа, вы можете указать значение 1 в этом поле и тем самым сэкономить место в базе данных.

  • Make plural forms - образовывать формы множественного числа для существительных в соответствии с правилами английской грамматики.

  • Repeat entity parent package for screens - если сущность расположена в дополнительном пакете внутри пакета entity, Studio добавит этот пакет к пути стандартных экранов Generic UI, автоматически генерируемых по шаблонам. Например, если сущность Customer лежит в пакете com.company.sample.entity.crm, пакетом для её экранов по умолчанию будет com.company.sample.web.crm.customer.

  • Use underscores in generated package names - если флажок установлен, слова в именах пакетов будут разделены нижним подчёркиванием в соответствии с camel-регистром в имени соответствующей сущности. К примеру, при генерации экранов для сущности com.company.sample.CustomerGrade, имя пакета будет выглядеть как com.company.sample.customer_grade. Если опция выключена, пакет будет назван com.company.sample.customergrade.

  • Default parent package name for screens - здесь можно указать пакет по умолчанию, который будет использоваться для экранов вместо screens при генерации экранов пользовательского интерфейса, не относящимся к какой-либо сущности. Например, если в этом поле указать значение ui и создать пустой экран по шаблону blank screen, пакетом по умолчанию для этого экрана будет com.company.sample.web.ui.

  • Default access modifier - здесь можно установить модификатор доступа для генерируемых полей сущностей.

  • Generate entity name with underscore symbol - если флажок установлен, имена сущностей будут образованы в формате namespace_ClassName, например, sales_Customer. В противном случае будет использован формат namespace$ClassName.

  • Show module prefix migration dialog - при открытии проекта предлагать миграцию скриптов сборки на новый формат с префиксом модулей, заданным в виде переменной.

  • Instant hot deploy - этот флажок позволяет отключить механизм мгновенного применения изменений (hot deploy). Если hot deploy разрешён, Studio будет динамически обновлять UI уже развёрнутого приложения по мере внесения изменений в представления (views), экраны, пакеты сообщений или главное меню.

  • Hot Deploy Settings - открывает диалоговое окно, в котором можно настроить каталоги hot deployment. Это может быть полезно в случае, если вы захотите добавить, например, каталоги, где размещены файлы HTML и JavaScript модуля web portal вашего проекта. При изменении этих файлов Studio будет копировать их в соответствующие каталоги внутри Tomcat. Таким образом, чтобы увидеть изменения, вам потребуется всего лишь перезагрузить страницу веб-портала.

  • Fold messages in - позволяет контролировать свёртывание сообщений в дескрипторах и контроллерах экрана. Если флажок установлен, ключи сообщений будут заменены на их реальные значения из соответствующих пакетов сообщений.

  • Message folding locale - позволяет указать, сообщения из какого пакета (какой локали) должны быть использованы при свёртывании.

5. Функции и возможности Studio

В этом разделе описаны возможности и особенности Studio, которые позволят вам быстрее и удобнее разрабатывать приложения на платформе. Информация в данном разделе структурирована, по большей части, в соответствии с элементами дерева проекта, которое вы видите в левой части Studio.

Некоторые функции Studio могут пересекаться с отдельными функциями IntelliJ Ultimate Edition или сторонних плагинов. К примеру, чтобы избежать конфликта значков в жёлобе (gutter), необходимо запретить конфликтующие Ultimate-значки. Сделать это можно следующим образом:

  • В меню IDEA выберите Settings > Editor > General > Gutter Icons,

  • Снимите флажки с опций Injection points и Producers for Disposer methods,

  • Сохраните изменения.

5.1. Конфигурация проекта

Здесь описаны средства для настройки конфигурации проекта и управления его инфраструктурой.

5.1.1. Редактор свойств проекта

Окно Project Properties позволяет настроить конфигурацию конкретного проекта. Окно редактора свойств можно открыть из главного меню CUBA или двойным кликом по элементу дерева Project > Properties.

Вкладка Main

На вкладке Main располагаются основные настройки проекта.

  • Поле Repositories отображает список репозиториев, используемых в текущем проекте. Studio сканирует эти репозитории и выводит доступные в них версии платформы. Чтобы настроить доступ к репозиторию, используйте кнопки рядом с полем. Более подробно о настройках доступа смотрите в документации. Также вы можете вручную настроить доступ к любому количеству дополнительных репозиториев, содержащих компоненты приложения, зарегистрировав их в файле build.gradle.

  • В поле Platform version можно выбрать желаемую версию платформы. При выборе более новой версии Studio при необходимости осуществит автоматическую миграцию проекта.

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

  • Если необходимо изменить путь к серверу приложений, укажите новый путь в поле Tomcat path. При следующем вызове команды gradlew deploy или gradlew start сервер Tomcat будет установлен в указанный каталог.

  • Группа полей Tomcat ports позволяет указать нестандартные порты для сервера приложений Tomcat, установленного в каталог deploy/tomcat в результате быстрого развёртывания приложения.

  • В частности, поле HTTP port определяет порт, который сервер Tomcat слушает для установки HTTP-соединения, аналогично свойствам приложения cuba.webPort, cuba.webAppUrl, cuba.restApiUrl и cuba.connectionUrlList.

  • В поле AJP port можно указать порт AJP-коннектора.

  • Поле Shutdown port позволяет задать порт, на котором Tomcat будет отслеживать команду SHUTDOWN.

  • Поле Debug port определяет порт, который сервер Tomcat слушает для подключения к отладчику (debugger) Java. После изменения этого порта необходимо также изменить его в настройках отладчика в IDE.

  • В поле Available locales вы можете указать локали, используемые в приложении. Откройте редактор локалей, нажав на кнопку рядом с полем. Флажок Locale select visible в окне редактора управляет свойством приложения cuba.localeSelectVisible. В редакторе также можно определить и переопределить формат строк для распознавания и форматирования дат.

  • Флажок Groovy support позволяет использовать код Groovy в приложении: например, в классах контроллеров экранов.

Вкладка Data Stores

На вкладке Data Stores отображается настройки подключения вашего проекта к одной или нескольким базам данных.

  • В верхней части редактора расположены настройки основного хранилища данных проекта.

    • Тип сервера базы данных можно выбрать в поле Database type. В полях ниже вы можете настроить URL подключения к базе данных, указать имя пользователя, пароль и дополнительные параметры подключения.

    • Формат параметров подключения зависит от типа выбранной СУБД. Строка параметров должна содержать разделитель между именем базы данных и непосредственно параметрами. К примеру, чтобы указать имя экземпляра Microsoft SQL Server 2008+, нужно ввести в поле следующую строку:

      ;instanceName=myinstance
    • Нестандартный URL подключения к БД можно указать в случае, если установлен флажок Custom database URL. В этом случае необходимо также указать значения Host и Database, так как в скрипте build.gradle эти значения используются по отдельности.

    • Если выбрана HSQLDB, Studio сама обеспечит создание и подключение к БД. Созданные файлы БД будут сохранены в каталог build/hsqldb.

  • Панель Additional data stores содержит список дополнительных хранилищ данных, к которым подключен проект. При создании и редактировании дополнительного хранилища открывается диалоговое окно Data Store, которое содержит следующие поля:

    • Data store name - имя хранилища данных. Может содержать только буквенно-числовые символы и нижние подчеркивания, а также должно отличаться от имени проекта.

    • Data store type - тип хранилища: RdbmsStore или Custom, более подробно см. в основном Руководстве. В случае, если выбран тип RdbmsStore, необходимо также заполнить следующие поля, описанные ниже.

    • DataSource JNDI name - устанавливается автоматически в Studio на основе имени хранилища.

    • Database type, URL, и т.д. - параметры подключения к БД.

5.1.2. Управление модулями

Studio позволяет создавать, редактировать и удалять дополнительные модули проекта: core, gui, web, web-toolkit, portal и front. Для управления модулями используйте команды в меню CUBA > Advanced > Manage Modules или в контекстном меню Project > Modules дерева проекта.

В секции Modules дерева проекта отображаются модули, используемые в текущем проекте. При создании нового проекта в нём автоматически создаются модули global, core и web. Для каждого модуля Studio отображает файлы конфигурации, расположенные в этом модуле.

5.1.3. Настройки развёртывания

Специальные экраны редакторов Studio помогут вам настроить задачи Gradle для сборки артефактов развёртывания. Эти редакторы можно открыть из главного меню CUBA > Deployment или по двойному клику на элементе дерева Project > Deployment.

Редактор WAR Settings позволяет настроить сборку WAR файлов. После завершения настройки в файле build.gradle будет автоматически создана задача buildWar.

  • Build WAR - установка этого флажка создаст задачу buildWar в файле build.gradle.

  • Include JDBC driver - определяет, нужно ли включать в WAR-файл драйвер JDBC.

  • Include Tomcat’s context.xml - определяет, нужно ли включать в WAR-файл конфигурационный файл context.xml (дескриптор развёртывания Tomcat).

  • Custom context.xml path - путь к дескриптору развёртывания Tomcat context.xml относительно корневого каталога приложения. Поле доступно, если установлен флажок Include Tomcat’s context.xml. Нажмите Generate, чтобы создать этот файл автоматически.

  • Single WAR for Middleware and Web Client - определяет, нужно ли объединять блоки приложения Middleware и Web Client в один единый WAR-файл.

  • Custom web.xml path - файл, который будет использован в качестве собственного web.xml единого WAR-файла. Нажмите Generate, чтобы создать этот файл автоматически.

  • Logback configuration file - путь к конфигурационному файлу logback.xml относительно корневого каталога приложения. Нажмите Generate, чтобы создать этот файл автоматически.

  • App properties - набор свойств приложения, имеющих отношение к этому развёртыванию. Свойства будут добавлены в файл /WEB-INF/local.app.properties внутри WAR.

Редактор UberJAR Settings позволяет настроить сборку Uber JAR. После завершения настройки в файле build.gradle будет автоматически создана задача buildUberJar.

  • Build Uber JAR - установка этого флажка создаст задачу buildUberJar в файле build.gradle.

  • Single Uber JAR - если флажок установлен, задача buildUberJar создаст единый Uber JAR для всех модулей проекта.

  • Logback configuration file - путь к конфигурационному файлу logback.xml относительно корневого каталога приложения. Нажмите Generate, чтобы создать этот файл автоматически.

  • Custom Jetty environment file - путь к конфигурационному файлу jetty-env.xml относительно корневого каталога приложения. Этот файл будет использоваться встроенным сервером Jetty. Поле обязательно к заполнению. Нажмите Generate, чтобы создать этот файл автоматически.

  • App properties - набор свойств приложения, имеющих отношение к этому развёртыванию. Свойства будут добавлены в файл /WEB-INF/local.app.properties внутри Uber JARs.

  • В полях Core port, Web port, Portal port можно настроить порты встроенных серверов для соответствующих блоков приложения. Поле недоступно, если выбрана опция Single Uber JAR. Значения портов по умолчанию описаны в основном руководстве. Кроме того, порты можно указать в качестве аргументов при запуске JAR из командной строки с помощью команды -port.

5.2. Модель данных

Данный раздел посвящён моделированию предметной области приложения и работе с классами сущностей и базой данных.

5.2.1. Операции над сущностями

Создание новой сущности
  1. Выберите элемент Data Model или вложенный в него пакет в дереве проекта и в контекстном меню нажмите New > Entity.

  2. В появившемся окне New CUBA Entity введите имя класса сущности в поле Entity name, выберите тип сущности и её идентификатор.

  3. Studio создаст класс сущности и зарегистрирует его в файле persistence.xml или metadata.xml в зависимости от типа сущности. Созданный класс откроется в редакторе исходного кода, в нижней части которого можно увидеть три вкладки:

    • Text содержит исходный код класса.

    • Designer содержит визуальный дизайнер, который поможет вам настроить сущность и её атрибуты с помощью графического интерфейса, избавив вас от необходимости написания Java-кода вручную.

    • DDL Preview содержит доступный только для чтения DDL-код таблиц сущности и, при необходимости, ограничений по внешнему ключу.

Создание атрибутов сущности

Есть несколько способов добавления атрибутов сущности.

  • С помощью графического интерфейса дизайнера сущности: переключитесь на вкладку Designer, нажмите New под таблицей Attributes и заполните необходимые поля в окне редактора New Attribute.

    Кнопка рядом с полем Name поможет сразу же задать удобочитаемое имя атрибута для пользовательского интерфейса. Оно будет храниться в файле messages.properties и использоваться по умолчанию в компонентах UI. Если ваше приложение поддерживает несколько языков, вы также можете задать локализованное имя атрибута для каждого языка.

    attribute l10n
  • В отдельном окне, открываемом из исходного кода класса сущности. Поместите курсор под последним существующим полем класса и нажмите Alt+Insert (Cmd+N). В меню Generate выберите Add Attribute. Studio отобразит окно New Attribute, как если бы оно было открыто из визуального дизайнера.

    new attribute 2
  • Вы можете создать поле атрибута и вручную, сгенерировать для него геттер и сеттер, а затем выбирать JPA Annotations в меню Generate, чтобы добавить JPA-аннотации с параметрами по умолчанию.

Studio поможет добавить новые атрибуты к экранам UI, уже созданным для данной сущности. Поместите курсор на строку, в которой описан атрибут, и нажмите Alt+Enter (Option+Enter), или кликните по значку с лампочкой и выберите Add entity attribute to screens:

add attribute to screens

По нажатию клавиши Enter в Studio откроется диалоговое окно со списком экранов, работающих с редактируемой сущностью. Выберите нужные экраны, и Studio сама добавит атрибут к подходящим визуальным компонентам этих экранов, например, к таблице или форме редактирования.

Создание имени экземпляра сущности

Для сущностей, которые будут использоваться в качестве ссылочных атрибутов других сущностей (как, например, Customer может быть атрибутом сущности Order), необходимо задать шаблон для генерации осмысленного имени экземпляра этих сущностей. Этот шаблон задаётся с помощью аннотации @NamePattern класса сущности. Аннотацию можно создать средствами Studio, для этого нужно поместить курсор в любом месте кода класса, нажать Alt+Enter (Option+Enter) и выбрать Add name pattern (этот пункт доступен только для тех классов, для которых аннотация @NamePattern ещё не задана):

create name pattern

Нажмите Enter, и Studio отобразит список всех имеющихся атрибутов сущности. Выберите один или несколько атрибутов и нажмите Enter, после чего Studio сгенерирует аннотацию @NamePattern над классом сущности.

Создание строк сообщений для новых атрибутов

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

create message 1

Нажмите Alt+Enter (Option+Enter) на выделенном атрибуте и выберите пункт Create message in the message bundle:

create message
Удаление сущностей

При удалении класса сущности используйте опцию Safe delete для того, чтобы найти и удалить ссылки на данную сущность:

remove entity

Некоторые ссылки, например в файлах persistence.xml и metadata.xml, будут удалены автоматически. При наличии других ссылок, будет показан диалог, в котором они будут перечислены. Нажмите в нем View Usages, просмотрите ссылки в окне инструментов Find и нажмите Cancel или Do Refactor.

5.2.2. Работа с представлениями

Для создания нового представления, или view, выберите сущность в дереве проекта и нажмите New > View в её контекстном меню.

create view

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

  • Entity name - имя сущности, для которой создаётся представление.

  • Name - имя нового представления.

  • Extends - встроенное или собственное представление, чьи атрибуты будет наследовать новое представление. Для любой сущности в платформе определены следующие представления по умолчанию:

    • _local включает в себя все локальные атрибуты сущности, т.е. атрибуты, которые не содержат ссылок на другие сущности,

    • _minimal включает в себя атрибуты, входящие в имя экземпляра сущности и задаваемые аннотацией @NamePattern,

    • _base включает в себя все локальные несистемные атрибуты и атрибуты, заданные в аннотации @NamePattern (т.е. фактически _minimal + _local).

  • Configuration file - файл конфигурации представлений, в котором будет сохранено текущее представление. По умолчанию Studio создаёт единственный файл views.xml в модуле global.

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

Если ваше представление наследует другое представление, все унаследованные атрибуты будут выбраны автоматически, а их чекбоксы будут неактивны.

Когда вы выбираете ссылочный атрибут, в панели справа отобразятся следующие свойства:

  • Entity - имя сущности, на которую указывает ссылка.

  • View - необязательное имя представления, с которым должна быть загружена эта сущность. Мы рекомендуем ссылаться на конкретное представление вместо произвольного набора атрибутов, так вам будет проще поддерживать сложные многоуровневые представления. Кроме того, даже если вы указали имя конкретного представления, вы по-прежнему можете добавить к нему отдельные атрибуты, не включённые в это представление, с помощью чекбоксов в дереве атрибутов.

  • Fetch - дополнительное свойство ссылочных атрибутов, которое определяет тип загрузки связанной сущности из базы данных. Подробнее о типах загрузки см. в основном руководстве.

Когда вы нажмёте OK и закроете дизайнер представлений, вы сможете увидеть созданное представление в дереве проекта под сущностью:

create view 2

Двойной клик по представлению в дереве проекта откроет файл конфигурации views.xml и установит курсор на определении этого представления. В нижней части редактора можно увидеть две вкладки: Text и Structure. Последняя отображает список представлений, описанных в этом файле конфигурации.

При редактировании представления в XML-дескрипторе используйте автодополнение имён атрибутов с помощью комбинации Ctrl+Space:

view edit 1

Обратите внимание, если некоторые атрибуты подсвечены: с большой долей вероятности их не существует в данной сущности:

view edit 2

Открыть графический дизайнер представлений можно несколькими способами:

  • Выбрав представление в дереве проекта, нажать Edit View в его контекстном меню;

  • Поместив курсов на элемент view в коде файла конфигурации представлений, нажать Alt+Enter (Option+Enter), выбрать Edit view во всплывающем меню и нажать Enter;

  • Переключившись на вкладку Structure в редакторе файла конфигурации представлений, выбрать нужное представление и нажать на кнопку Edit.

5.2.3. Работа с базой данных

Studio умеет создавать DDL-скрипты для создания и поддержания схемы базы данных, соответствующей моделируемым сущностям. Созданные скрипты могут быть выполнены как с помощью Studio, так и прямым вызовом задач Gradle, а также самим приложением при его запуске.

Для того, чтобы создать DDL-скрипты средствами Studio, нажмите CUBA > Generate Database Scripts в главном меню, либо выберите элемент Data Model в дереве проекта и нажмите Generate Database Scripts в его контекстном меню.

Откроется окно Studio Database Scripts, которое содержит следующие вкладки:

Updates

На вкладке Updates отображаются скрипты обновления базы данных для её соответствия текущему состоянию модели данных приложения. Созданные скрипты сохраняются в каталоге modules/core/db/update. Имена скриптов генерируются автоматически и содержат префиксы, которые определяют порядок выполнения скриптов. Скрипты, содержащие команду DROP, подсвечиваются красным.

Вы можете добавить дополнительный скрипт, нажав на кнопку Create, он будет сохранён и позже выполнен вместе с остальными сгенерированными скриптами.

Новые скрипты можно отредактировать или удалить совсем, нажав на кнопку Remove.

Если нажать на кнопку Exclude selected (исключить), вам будут предложены два варианта:

  • Перенести скрипт в папку с исключёнными вручную скриптами: modules/core/db/update-manually. В этом случае скрипт не будет исполнен автоматически при выполнении команды Update database, но вы всегда сможете выполнить его вручную, когда потребуется. Этот вариант удобен для скриптов, удаляющих столбцы и таблицы, ранее переименованные в *__UNUSED.

  • Исключить скрипт: в этом случае он не будет сохранён в папке modules/core/db/update, но будет зафиксирован в файле studio-intellij.xml в каталоге проекта. В следующий раз, когда вы будете генерировать скрипты, Studio проигнорирует изменения, соответствующие исключённым скриптам. Этот вариант позволяет иметь различия между схемой БД и сущностями модели данных приложения.

    Например, вам может понадобиться добавить поле в таблицу БД, соответствующую некой сущности, не сопоставляя его с атрибутом сущности. Когда Studio создаст скрипт для удаления этого поля из базы данных, просто исключите его, и Studio не будет генерировать его снова.

Init Tables

Скрипт Init Tables создаёт все таблицы в базе данных при выполнении команды Create Database. Он выполняется до скриптов Init constraints и Init data. Вы можете редактировать этот скрипт, но обязательно сохраните комментарии, разделяющие таблицы. Скрипт хранится в файле 10.create-db.sql.

Init Constraints

Скрипт Init Constraints служит для создания ограничений целостности. Он выполняется сразу после Init tables. Этот скрипт также можно редактировать, не удаляя комментариев-разделителей. Скрипт хранится в файле 20.create-db.sql.

Init Data

Скрипт Init Data позволяет добавить дополнительную информацию или схему, которой нет в модели данных. Этот скрипт выполняется последним при инициализации БД. Скрипт хранится в файле 30.create-db.sql.

Если проект содержит компоненты приложения (аддоны), для которых нет DDL-скриптов для текущей базы данных, Studio сама создаст скрипты для этих компонентов и отобразит их на вкладках Init {component} tables и Init {component} constraints. Такие скрипты сохраняются в файлах 01.{component}-create-db.sql и 02.{component}-create-db.sql соответственно.

Нажмите Save and close для сохранения сгенерированных скриптов. Теперь вы можете найти их в секции Project > Data Stores > Main Data Store дерева проекта.

Чтобы запустить скрипты обновления, остановите сервер приложения, если он был запущен, и выполните команду Update Database в главном меню CUBA. Если вы хотите заново создать базу данных с нуля с помощью скриптов инициализации, выполните команду Create Database.

5.2.4. Генерация модели данных

Studio позволяет легко создавать модель данных приложения и стандартные экраны UI поверх существующей базы данных. Нажмите CUBA > Advanced > Generate Model в главном меню или выберите Project > Data Stores в дереве проекта и нажмите Generate Model в контекстном меню. Если приложение подключено к нескольким хранилищам данных, выберите один из них в отобразившемся окне Studio.

После этого Studio запустит мастер генерации модели Generate Model from Database.

Шаг 1

Это первый шаг генерации модели данных с помощью мастера.

generate model step1

Дополнительный шаг: вы можете нажать на кнопку Settings, чтобы выбрать пакет Java, в который нужно поместить новые сущности, и настроить сопоставление (mapping) системных атрибутов по умолчанию.

К примеру, если все или большинство таблиц в вашей базе данных содержат столбцы Modified и ModifiedBy, вы можете сопоставить их с атрибутами Updatable.updateTs и Updatable.updatedBy для всех генерируемых сущностей. В этом случае вам не придётся настраивать сопоставление этих атрибутов индивидуально для каждой сущности. Используйте список Exclude columns from mapping, если вы хотите исключить некоторые столбцы из автоматического сопоставления для всех таблиц.

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

Выберите таблицы, которые вы хотите отразить в своей модели данных. Некоторые таблицы могут быть связаны с другими через внешние ключи, и когда вы выбираете такую таблицу, все связанные с ней таблицы выбираются автоматически. Если снимаете выделение с такой таблицы, все зависимые таблицы также становятся невыбранными.

Чекбокс справа поможет выбрать или снять выбор сразу со всех доступных таблиц.

Нажмите Next.

Шаг 2

На этом шаге вы можете просмотреть и отредактировать сопоставление атрибутов, которое было создано автоматически для выбранных таблиц.

generate model step2

В столбце Status отображается результат автоматического сопоставления:

  • OK - автоматическое сопоставление прошло успешно, все столбцы полностью отражены в новых сущностях.

  • Join table - связь между сущностями распознана и отражена в виде связанной таблицы many-to-many.

  • There are unmapped columns - некоторые столбцы не могут быть отражены в новых сущностях.

  • New PK will be created - таблица не имеет первичного ключа. Будет создан новый первичный ключ с типом UUID.

  • Composite PK will be replaced - таблица имеет составной первичный ключ, но на него нет ссылок из других таблиц. Составной первичный ключ будет заменён первичным ключом с типом UUID.

  • Composite PK referenced by other tables - таблица имеет составной первичный ключ, на который ссылаются другие таблицы. Studio не может сопоставить такую таблицу.

  • Unsupported PK type - таблица имеет первичный ключ неподдерживаемого типа. Studio не может сопоставить такую таблицу.

  • Choose primary key for DB view - данная таблица является представлением (view), и вы должны выбрать один или несколько столбцов, которые будут использованы в качестве идентификатора сущности. Для этого нажмите кнопку Choose PK и выберите столбцы для первичного ключа.

Кнопка Refresh mapping позволяет заново выполнить автоматическое сопоставление для выбранных таблиц. Таким образом, вы можете, к примеру, внести изменения в схему БД в некоем стороннем клиенте баз данных, а затем вернуться в мастер Studio и перезапустить процедуру сопоставления.

Кнопка Edit mapping открывает диалоговое окно, в котором отображаются подробности данного сопоставления. Здесь вы можете изменить имя будущей сущности и список системных интерфейсов, которые должен реализовывать класс сущности. Это влияет на количество системных столбцов, которые будут созданы в базе данных в целях совместимости с сущностями платформы.

generate model step2 2

Кнопка Choose PK появляется вместо кнопки Edit mapping, если выбрано представление (view) базы данных, и требуется отметить столбцы, которые будут использованы в качестве идентификатора сущности.

Нажав Back, вы можете вернуться к предыдущему шагу и изменить список выбранных таблиц.

Нажмите Next, чтобы перейти к следующему шагу.

Шаг 3

На этом этапе вы можете указать, какие экраны пользовательского интерфейса необходимо создать для новых сущностей.

generate model step3

Если вы снимете флажок Create standard screen, Studio не будет генерировать экраны UI для новых сущностей.

Используйте поля In module, Package и Menu, чтобы указать, где должен быть размещён исходный код создаваемых экранов и в какой части меню приложения они должны отображаться.

Используйте выпадающий список в столбце Standard screens, чтобы выбрать тип создаваемых экранов.

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

Нажмите Next, чтобы перейти к следующему шагу.

Шаг 4

Этот шаг завершает процесс генерации модели данных.

Таблица Import scripts содержит список скриптов, которые необходимо выполнить в базе данных, чтобы сделать её совместимой с создаваемыми сущностями.

До этого этапа никаких изменений не было ни внесено в проект, ни даже сохранено на диск. По факту, Studio выполняет генерацию сущностей и экранов и сохраняет скрипты только после того, как вы нажмёте Run all scripts или Run script.

Вы можете просмотреть и отредактировать скрипты на этой странице, затем выполнить их или просто сохранить, чтобы выполнить позднее в любой отдельной утилите для управления базами данных. Скрипты импорта сохраняются в папку проекта modules/core/db/import.

5.2.5. Поддержка произвольной СУБД

Как описано в документации, вы можете реализовать работу с любой СУБД, поддерживаемой фреймворком EclipseLink ORM, на уровне конкретного проекта. Studio позволяет автоматически создавать файлы, необходимые для интеграции с нестандартными СУБД.

Выберите CUBA > Advanced > Define Custom Database в главном меню.

В открывшемся окне можно указать свойства базы данных, с которой вы хотели бы работать. На основе указанных свойств Studio сгенерирует код для поддержки выбранной СУБД как на этапе разработки, так и в готовом приложении.

  • DB type id - идентификатор типа СУБД, который будет использован в качестве значения свойства cuba.dbmsType.

  • DB type name - удобочитаемое имя БД, которое будет отображаться в Studio.

После нажатия OK Studio создаст классы Java в пакете com.haulmont.cuba.core.sys.persistence и классы Groovy в пакете com.haulmont.studio.db.{db_id} вашего проекта. Базовая реализация, сгенерированная в Studio, подходит для использования СУБД Microsoft SQLServer. Вы можете изменить её при необходимости.

Для начала приведите класс com.haulmont.studio.db.{db_id}.{db_id}DbProperties в соответствие с выбранной вами базой данных. После этого вы сможете выбирать эту СУБД в настройках проекта в Studio. Закройте проект и переоткройте его заново, чтобы в списке доступных СУБД появилась нужная.

Чтобы подключиться к новой базе данных из работающего приложения, скорректируйте классы {db_id}DbmsFeatures и {db_id}DbTypeConverter в пакете com.haulmont.cuba.core.sys.persistence. Класс {db_id}SequenceSupport используется только для генерации целочисленных идентификаторов и уникальных чисел.

Наконец, если это необходимо, модифицируйте класс com.haulmont.studio.db.{db_id}.{db_id}DdlGenerator для правильной генерации скриптов init и update в Studio. Пропустите этот шаг, если вы не планируете создавать DDL-скрипты для новой базы данных.

Если вы планируете использовать нестандартную СУБД в качестве основного хранилища данных проекта, сгенерируйте скрипты инициализации и обновления БД, чтобы Studio могла создать init-скрипты для всех компонентов приложения, включая сам фреймворк. Эти скрипты не включают в себя некоторые данные, необходимые для инициализации БД, поэтом добавьте вручную следующие команды в скрипт Init data вашего проекта (30.create-db.sql):

insert into SEC_GROUP (ID, CREATE_TS, VERSION, NAME, PARENT_ID)
values ('0fa2b1a5-1d68-4d69-9fbd-dff348347f93', current_timestamp, 0, 'Company', null)^

insert into SEC_USER (ID, CREATE_TS, VERSION, LOGIN, LOGIN_LC, PASSWORD, NAME, GROUP_ID, ACTIVE)
values ('60885987-1b61-4247-94c7-dff348347f93', current_timestamp, 0, 'admin', 'admin',
'cc2229d1b8a052423d9e1c9ef0113b850086586a',
'Administrator', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', 1)^

insert into SEC_USER (ID, CREATE_TS, VERSION, LOGIN, LOGIN_LC, PASSWORD, NAME, GROUP_ID, ACTIVE)
values ('a405db59-e674-4f63-8afe-269dda788fe8', current_timestamp, 0, 'anonymous', 'anonymous', null,
'Anonymous', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', 1)^

5.3. Компоненты среднего слоя

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

5.3.1. Создание сервисов

Сервисы - это управляемые контейнером компоненты, формирующие границу приложения и предоставляющие интерфейс клиентскому уровню приложения. Сервисы могут содержать бизнес-логику сами, либо делегировать выполнение управляемым бинам.

Чтобы создать новый сервис, в контекстном меню элемента Middleware в дереве проекта выберите New > Service:

create service

Введите имя интерфейса сервиса. После этого будут автоматически сгенерированы константы имён соответствующего бина и самого сервиса:

create service 2

Интерфейс сервиса будет создан в модуле global, а его реализация - в модуле core. Также новый сервис будет автоматически зарегистрирован в файле конфигурации web-spring.xml.

Маркер в жёлобе Studio позволяет легко переключаться между интерфейсом и бином сервиса:

service interface

Когда вы создаёте новый метод в интерфейсе сервиса, Studio сама проверит наличие его реализации, и если реализация не найдена, предложит создать её в классе бина сервиса:

service interface 2

5.3.2. Создание бинов

Studio отображает все управляемые бины среднего слоя, включая entity listeners и transaction listeners, в элементе Middleware > Beans дерева проекта.

studio beans

Для создания управляемого бина нужно создать новый Java-класс: выберите нужный пакет в дереве проекта и выберите New > Java Class в его контекстном меню. Затем добавьте классу аннотацию @Component, как в примере выше. Чтобы избежать конфликта имён, особенно при разработке компонента приложения, рекомендуется явно указать уникальное имя бина в этой аннотации.

5.4. Универсальный пользовательский интерфейс

Studio предлагает широкий набор возможностей для оптимизации работы с пользовательским интерфейсом приложения.

В секции Generic UI дерева проекта вы можете найти следующие элементы:

  • Web Menu открывает графический редактор главного меню приложения.

  • Main Message Pack содержит строки сообщений для элементов главного меню и общих элементов UI приложения.

  • Screens отображает созданные экраны.

  • Themes используется для управления темами визуального представления приложения.

5.4.1. Создание и удаление экранов

Чтобы создать экран пользовательского интерфейса, выберите New > Screen в контекстном меню элемента Generic UI в дереве проекта. Если вы хотите создать CRUD-экраны для сущности, выберите эту сущность или одно из её представлений в дереве проекта и также нажмите New > Screen в контекстном меню:

create screen

Studio отобразит список доступных шаблонов экранов. Список разделён на две секции: Screen Templates и Legacy Screen Templates. Первая содержит шаблоны экранов, для которых доступен новый API начиная с версии 7 фреймворка, тогда как в секции Legacy содержатся экраны, которые совместимы также с версией 6.

create screen 2

При создании экрана для сущности или её представления, выбранных в дереве проекта, поля Entity и View будут заполнены автоматически:

create screen 3

В секции Advanced мастера создания экрана вы можете изменить стандартные имена дескриптора и контроллера экрана, а также его идентификатор. Это может потребоваться, если вы планируете создать более одного экрана для выбранной сущности.

Когда вы нажмёте Finish, будут созданы и открыты файлы XML-дескриптора и Java-контроллера экрана. Старые экраны, не имеющие аннотации UiDescriptor и/или @UiController, дополнительно будут зарегистрированы в конфигурационном файле web-screens.xml.

При удалении файлов экрана используйте опцию Safe delete для того, чтобы найти и удалить ссылки на данный экран:

safe delete screen 1

Некоторые ссылки, например в файлах web-menu.xml и web-screens.xml, будут удалены автоматически. При наличии других ссылок, будет показан диалог, в котором они будут перечислены. Нажмите в нем View Usages, просмотрите ссылки в окне инструментов Find и нажмите Cancel или Do Refactor:

safe delete screen 2

5.4.2. Работа с дескриптором экрана

Редактор XML-дескриптора экрана содержит две вкладки: Text и Designer. На вкладке Text вы можете редактировать код XML напрямую, а вкладка Designer позволяет работать с экраном в визуальном редакторе разметки.

xml descriptor

Переключаться между дескриптором и контроллером экрана можно с помощью специального маркера в жёлобе Studio. Также вы можете выбрать дескриптор в дереве проекта и в его контекстном меню нажать Go to controller.

Studio непрерывно инспектирует код разметки экрана на предмет ошибок и несоответствий, проверяет внутренние и внешние ссылки. В случае обнаружения следующих проблем Studio покажет специальное предупреждение или подчеркнёт проблемный элемент в XML-коде:

  • Экран не может быть собран из-за ошибки в разметке XML.

  • Ссылка на сущность или её свойство, используемая компонентом, не соответствует реальной модели данных приложения.

  • Есть конфликт размеров компонентов: учитываются значения атрибутов width, height и expand.

  • Значения атрибутов dataContainer и dataLoader не ссылаются ни на один из имеющихся контейнеров или загрузчиков.

  • Для полей внутри элемента form явно не определён XML-атрибут property: в этом случае для ссылки на поле сущности будет неявно использовано значение атрибута id.

  • Семантическая ошибка в элементе form: поля дублируются или располагаются не внутри вложенного элемента column.

  • Количество столбцов gridLayout не соответствует заявленному количеству.

  • Дублирование атрибута в расширенном экране, когда один и тот же атрибут объявлен и в родительском, и в дочернем экране.

  • Имена элементов в дочернем экране не соответствуют аналогичным элементам в родительском экране, либо их расположение некорректно.

  • Значение атрибута messagesPack не ссылается на реально существующий пакет сообщений, содержащий как минимум один файл messages_xx.properties.

  • Ссылка на схему XSD устарела.

  • Значения идентификаторов элементов не уникальны внутри данного экрана.

Эти инспекции можно настроить в окне Settings (CUBA > Settings > Editor > Inspections).

На вкладке Designer отображается визуальный дизайнер, который позволяет создавать компоновку экрана и задавать свойства компонентов UI в стиле WYSIWYG.

xml descriptor 2

Рабочая область дизайнера включает в себя четыре панели:

  • Canvas - рабочая область, в которой вы можете располагать компоненты, а также изменять их размер и задавать выравнивание с помощью кнопок:

    • расширить горизонтально,

    • расширить вертикально,

    • выровнять по вертикали/горизонтали.

  • Palette - палитра, содержащая набор доступных экранных компонентов:

    • Контейнеры;

    • Компоненты;

    • Компоненты данных: контейнеры и загрузчики;

    • Не-визуальные компоненты: действия, настройки диалогового окна, таймеры.

Чтобы добавить компонент на экран, перетащите его из палитры на полотно или в панель иерарархии компонентов.

  • Hierarchy - панель иерархии компонентов, отображающая использованные в экране компоненты в виде дерева. Элементы дерева можно перетаскивать с места на место, иногда это даже удобнее, чем перемещать их по полотну. Вы можете удалять, копировать, вырезать или вставлять элементы в дерево иерархии с помощью его контекстного меню, открываемого по клику правой кнопки мыши.

  • Properties - панель, отображающая свойства конкретного визуального компонента.

5.4.3. Работа с контроллером экрана

Данный раздел посвящён возможностям Studio для работы с кодом контроллеров экранов.

Специальные значки в жёлобе Studio позволяют быстро переключаться между дескриптором и контроллером экрана, позиционировать курсор на нужном XML-элементе инжектированного компонента и т.д.

controller
Инжекция зависимостей

Механизм Dependency injection - это основной способ получения ссылок на визуальные компоненты и элементы API в коде контроллера экрана. Конечно, вы можете описать поле нужного типа и аннотировать его вручную, но Studio предоставляет возможность выбрать нужный объект из списка в специальном окне, чтобы создать требуемое поле автоматически. Это окно открывается по нажатию Alt+Insert (Cmd+N), далее нужно выбрать пункт Inject…​ в выпадающем меню Generate:

controller injection

Инжектировать в контроллеры можно следующие объекты:

  • Визуальные компоненты и компоненты данных, определенные в XML-дескрипторе,

  • Интерфейсы API экранов,

  • Интерфейсы инфраструктуры,

  • Сервисы среднего слоя,

  • Интерфейсы конфигурации.

Обработка событий

Создав обработчик некоего события, вы можете выполнять его код на разных этапах жизненного цикла экрана, например, реагировать на действия пользователя. Обработчик представляет собой отдельный метод в контроллере экрана с аннотацией @Subscribe, принимающий событие в качестве параметра. Такой метод можно создать в Studio: нажмите Alt+Insert (Cmd+N) и выберите Subscribe to Event в меню Generate:

subscribe dialog

Каждое событие в отобразившемся окне снабжено описанием Javadoc в правой части окна.

По умолчанию в окне доступны следующие события:

  • События контроллера для управления жизненным циклом экрана.

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

  • События фрейма для управления жизненным циклом внешнего фрейма, в который включён данный экран.

  • События контекста данных, позволяющие реагировать на изменения data context и выполнять код до и после сохранения данных в экране.

  • События контейнеров данных, которые могут получать уведомления об изменении состояний контейнеров данных и хранимых в них сущностей.

Делегаты

Используя делегаты, вы можете написать код, который должен использоваться различными механизмами экранов вместо их стандартной реализации. К примеру, вы можете написать свою собственную функцию для сохранения изменённых данных или переопределить значки для строк таблицы.

Делегат представляет собой метод контроллера экрана со специальной подписью и аннотацией @Install. Такой метод также можно создать в Studio, нажав Alt+Insert (Cmd+N) и выбрав Install Delegate в меню Generate:

install dialog

Каждый делегат в отобразившемся окне снабжён описанием Javadoc в правой части окна.

5.4.4. Работа с меню приложения

Дизайнер меню позволяет задать элементы главного меню приложения и сохранить их в конфигурационном файле web-menu.xml. На вкладке Structure вы найдёте графический дизайнер меню, а его XML-код можно редактировать на вкладке Text.

web menu

Существует два режима создания меню:

  • Режим Single mode содержит только элементы, описанные в файле web-menu.xml. В этом режиме вам придётся вручную создавать все элементы меню, включая те, что были созданы в компонентах приложения. С другой стороны, этот режим предоставляет вам полный контроль над структурой меню.

  • Режим Composite mode включает в себя все элементы, описанные в файле menu.xml проекта, плюс элементы из конфигурационных файлов меню компонентов приложения. Этот режим позволяет легко использовать все унаследованные элементы и добавить к ним элементы, специфичные для данного проекта, в любое место в структуре меню. Унаследованные элементы отредактировать нельзя.

    Дополнительно на вкладке Text можно определить для элементов меню атрибуты ìnsertBefore и insertAfter, которые указывают, где должен быть размещён конкретный элемент меню. Эти атрибуты позволяют комбинировать элементы меню текущего проекта с элементами, унаследованными из компонентов, если выбран режим Composite.

    Например, если вы хотите поместить собственную структуру меню слева от стандартного элемента Administration, установите атрибут insertBefore="administration" для корневого элемента в вашей иерархии.

Список конфигурационных файлов меню задаётся свойством приложения cuba.menuConfig, значение которого обновляется при смене режима создания меню.

Чтобы добавить в меню новый элемент, выберите существующий элемент (или файл конфигурации, если нужно создать элемент верхнего уровня) и нажмите на кнопку +. Появится окно Menu item editor, в котором вы можете создать элемент меню с одним из следующих типов:

Screen
web menu create

Элемент меню, открывающий экран приложения.

Для элемента Screen необходимо определить следующие свойства:

  • Screen - неуникальный идентификатор экрана, который должен открывать этот элемент.

  • Id - дополнительный уникальный идентификатор элемента.

  • Open type - свойство, определяющее, как должен открываться экран: в новой вкладке или в виде модального окна (NEW_TAB или DIALOG). По умолчанию используется NEW_TAB.

  • Shortcut - горячие клавиши для открытия данного экрана. Допустимые модификаторы (ALT, CTRL, SHIFT) разделяются символом "-", например, ALT-C.

  • Style name - определяет имя стиля элемента, подробнее см. в разделе Темы приложения основного руководства.

Menu
web menu create 2

Элемент меню, содержащий другие элементы меню (подменю).

Для элемента Menu необходимо определить следующие свойства:

  • Id - дополнительный уникальный идентификатор элемента.

  • Style name - имя стиля элемента.

Bean
web menu create 3

Элемент меню, который вызывает определённый метод управляемого бина.

Для элемента Bean необходимо определить следующие свойства:

  • Id - дополнительный уникальный идентификатор элемента.

  • Bean - имя бина, которое можно получить с помощью AppBeans (к примеру, cuba_Messages).

  • Bean method - имя метода бина.

  • Shortcut - горячие клавиши для вызова метода. Допустимые модификаторы (ALT, CTRL, SHIFT) разделяются символом "-", например, ALT-C.

  • Style name - имя стиля элемента.

Class
web menu create 4

Элемент меню, который выполняет метод run() определённого класса.

Для элемента Class необходимо определить следующие свойства:

  • Id - дополнительный уникальный идентификатор элемента.

  • Class - полное имя класса, унаследованного от Runnable.

  • Shortcut - горячие клавиши для вызова метода. Допустимые модификаторы (ALT, CTRL, SHIFT) разделяются символом "-", например, ALT-C.

  • Style name - имя стиля элемента.

Separator

Горизонтальная линия, разделяющая элементы меню.

5.4.5. Изменение стиля приложения

В Studio можно легко и быстро создавать как расширения тем приложения, так и собственные темы.

theme extension

При создании расширения или новой темы в проекте будет создана специальная структура папок, а также будет изменён скрипт сборки build.gradle.

Все созданные темы отображаются в секции Themes дерева проекта.

halo ext

После расширения или создания темы вы можете изменять переменные стилей как вручную в файле SCSS, так и в визуальном редакторе: для этого в контекстном меню новой темы выберите пункт Open Variables File. Этот файл также можно открыть из главного меню CUBA: выберите Advanced > Manage themes > Edit theme variables.

theme variables