# Начало работы с фреймворком ## Требования к аппаратному обеспечению рабочего места разработчика |Характеристика сервера|Рекомендуемые параметры| |-|-| | ОС | Windows 10 и выше | | CPU | 8 ядер 3.5 GHz или более | | Оперативная память |16 – 32 Gb или более | | Память | SSD 20 Gb свободного места | | Монитор |разрешение 1920×1080 | Использование виртуальной машины может заметно снизить производительность при сборке и отладки проекта ## Создание новой БД для проекта Для создания базы данных используется команда `CREATE DATABASE`, после которой указывается название базы данных. Для выполнения запросов будем использовать графический клиент [pgAdmin](https://www.pgadmin.org/), хотя также можно использовать консольный клиент [psql](https://postgrespro.ru/docs/postgresql/14/app-psql). Создадим для проекта нового пользователя бд и базу данных, например: ```text Логин: sampleproject Пароль: sampleproject БД: sampleproject ``` Чтобы создать нового пользователя и новую БД: 1. Откройте [pgAdmin](https://www.pgadmin.org/). 2. Подключитесь под суперпользователем к СУБД. 3. В левой части программы выберите базу данных `postgres` 4. Выделите ее и правой кнопкой мыши запустите инструмент [Query Tool](https://www.pgadmin.org/docs/pgadmin4/latest/query_tool.html) ![pgAdminQueryTool](../img/pgAdminQueryTool.png) ### Создание пользователя В центральной части программы откроется поле для ввода кода SQL. 1. В окно запроса введите следующий код: ```sql CREATE ROLE sampleproject WITH LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT NOREPLICATION CONNECTION LIMIT -1 PASSWORD 'sampleproject'; GRANT pg_signal_backend TO "sampleproject"; ``` 2. Для создания пользователя выполним операцию `Execute/refresh`. ![pgAdminQueryTool](../img/CreateRole.png) ###  Создание БД 1. В окно запроса введите следующий код: ```sql CREATE DATABASE "sampleproject" WITH OWNER = "sampleproject" ENCODING = 'UTF8' CONNECTION LIMIT = -1; ``` 2. Для создания выполните операцию `Execute/refresh`. ###  Подключение расширений К созданной БД необходимо подключить расширения, которые использует система `Global`. Для этого: 1. Обновите список баз 2. В левой части программы выберите базу данных `sampleproject` 3. Выделите ее и правой кнопкой мыши запустите инструмент [Query Tool](https://www.pgadmin.org/docs/pgadmin4/latest/query_tool.html) ![pgAdminQueryTool](../img/ConnectToDb.png) 4. В окно запроса введите следующий код: ```sql CREATE EXTENSION if not exists plpgsql; CREATE EXTENSION if not exists fuzzystrmatch; CREATE EXTENSION if not exists pg_trgm; CREATE EXTENSION if not exists pg_stat_statements; CREATE EXTENSION if not exists "uuid-ossp"; CREATE EXTENSION if not exists dict_xsyn; CREATE EXTENSION if not exists ltree;  ``` 5. Для подключения расширений выполните операцию `Execute/refresh`. ## Настройка рабочего места ### Установка 1. Установите [IntelliJ IDEA Community Edition](https://www.jetbrains.com/ru-ru/idea/download/#section=windows) 2. Установите в IDE IntelliJ IDEA [SCALA Plugin](https://plugins.jetbrains.com/plugin/1347-scala) 3. Установите [Global3FrameworkStarterKit](http://helpcenter.gs.local/Global3FrameworkStarterKit/html/index.html) 4. Распакуйте архив с дистрибутивом сервера приложений `globalserver.zip` в директорию `C:\Global3se` 5. Скорипуйте проект в директорию `C:\Projects\projectName` ### Настройка переменных окружения Windows Добавьте переменные окружения Windows: - `G3_HOME = C:\Global3se` \ Путь к каталогу, в который разархивирован дистрибутив Global 3SE - `G3_PUBLISH = C:\Global3se\application` \ Путь к каталогу, в который будет производиться сборка проекта ### Настройка проекта Настройку проекта можно сделать в ручном и автоматическом режиме с помощью [gsf-cli - утилиты командной строки Global System Framework](http://helpcenter.gs.local/gsfcli/html/index.html) #### Развертывание вручную 1. Откройте в IDE `Intellij Idea` проект \ Для примера будем использовать путь: `C:\Projects\SampleProject\application` 2. Откройте файл `C:\Projects\SampleProject\application\project\orm\config\persistence.xml` 3. Поменяйте параметры соединения с БД Postgres проекта для `persistence-unit` `pgdev`: \ ```xml ``` Где: \ `eclipselink.jdbc.url` – строка соединения \ `eclipselink.jdbc.driver` – драйвер jdbc \ `eclipselink.jdbc.user` – пользователь бд \ `eclipselink.jdbc.password` – пароль ##### Конфигурация Global Server Перед запуском Global Server необходимо добавить информацию о проекте в конфигурационный файл. Для этого: 1. Откройте файл `C:\Global3se\application\config\global3.config.xml` в текстовом редакторе 2. В раздел `databases` добавьте новую базу данных ```xml ``` 3. В раздел `sbts` добавьте конфигурацию sbt ```xml ``` 4. В разделе `development` включить режим конфигуратора ```xml ``` #### gsf-cli - утилита командной строки Global System Framework gsf-cli - утилита командной строки Global System Framework предназначена для автоматизации работы разработчика Инструкция по развертыванию проекта в автоматическом режиме [Командная утилита G3Server](http://helpcenter.gs.local/gsfcli/html/index.html) ## Прикладной проект Прикладной проект собирает конечное решение из набора прикладных модулей. Собранное решение разворачивается не сервере приложения для работы с пользователями. ### Структура проекта - Проект(Application) - `build.sbt` \ Настройка сборки проекта - project \ Дополнительные настройки проекта - `модуль` - `src.main.java` - `src.main.scala` - `ru.bitec.app.[модуль]` \ Файлы модуля компилируемые языком scala - `src.main.resources` - `META-INF\module-info.xml` \ Мета данные о модуле - `ru.bitec.app.[модуль]` \ Файлы модуля не требующие компиляции - build.sbt \ Файл сборки модуля - `модуль_N` - `модуль_N+1` ```{attention} `ru.bitec.app.[moduleName]` – это **отдельные** каталоги! Точка в именах директорий запрещена! IDE Intellij Idea в обозревателе проекта группирует каталоги через точку для удобства просмотра ``` ### Модуль Каждый модуль представлен как отдельная директория со строго заданной системой подкаталогов. Для включения модуля в сборку необходимо объявить его и включить в агрегацию в корневом build.sbt проекта application. Модуль представляет собой некоторую неделимую совокупность функциональности системы, которая может быть включена в то или инной прикладной проект. Каждый объект, зарегистрированный в системе, принадлежит какому-либо модулю. Основными составляющими модуля являются классы, выборки и серверные методы, группированные в пакеты. #### Структура каталогов модуля `[moduleName]` \ Директория модуля разбита на строгую иерархию: - `[moduleName]/src/main/java/ru/bitec/app/[moduleName]` \ Содержит java сущности модуля: pojo классов, перечисления и т.д. Чаще всего сущности создаются автоматически генератором кода. - `[moduleName]/src/main/resources/META-INF` \ Содержит метаинформацию модуля: Описание, версию, зависимости, перечень приложений. - `[moduleName]/src/main/resources/orm` \ Содержит индексные файлы ORM. - `[moduleName]/src/main/resources/ru/bitec/app/[moduleName]` \ Содержит файлы моделей Odm, Orm, Dvm, Avm - `[moduleName]/src/main/scala/ru/bitec/app/[moduleName]` \ Содержит файлы прикладной бизнес-логики и контроллера view, пакетов: Dvi, Dpi, Api, Avi, Pkg - `[moduleName]/src/test/scala/ru/bitec/app/[moduleName]` \ Содержит юнит-тесты прикладных методов #### Зависимости Модуль может использовать или требовать наличия некоторого набора других модулей. Это требование выражается в том, что объекты, или функциональность, заложенная в модуль, не будут работать в случае отсутствия в системе другого, требуемого модуля. Зависимости позволяют увеличить повторное использование кода, за счет выделение частно используемого функционала в низкоуровневые модули. Базовые модули: - gtk \ Обеспечивает интеграцию с сервером приложения - btk \ Основная функциональность фреймворка, доступная всем более высокоуровневым модулям. Эти модули не требуют для своей работы наличия других модулей, являясь платформой системы. Зависимость модулей описывается в файле настроек сборки build.sbt для модуля. ##### Подключение внешних библиотек Допускается подключение к прикладным модулям внешних библиотек (`*.jar`). В файле build.sbt прикладного проекта необходимо прописать зависимость модуля от этих библиотек. ```scala lazy val bts = project. dependsOn(btk). settings(CommonSetting.setting: _*). settings( libraryDependencies ++= Seq( "org.apache.httpcomponents" % "httpmime" % "4.5.2", "org.apache.httpcomponents" % "httpcore" % "4.4.5", "org.apache.httpcomponents" % "httpclient" % "4.5.2" ) ) ``` Если подключаемая библиотека опубликована в нестандартном репозитории, необходимо объявить путь к этому репозиторию. ```scala lazy val btk = project. dependsOn(gtk). settings(commonSettings: _*). settings( resolvers += "nuiton-maven" at "https://nexus.nuiton.org/nexus/content/groups/releases/", libraryDependencies += "nl.knaw.dans.common" % "dans-dbf-lib" % "1.0.0-beta-10" ) ``` Если объявить зависимость с двумя символами "%", в качестве разделителя: `"nl.knaw.dans.common" %% "dans-dbf-lib" % "1.0.0-beta-10"` к имени библиотеки будет добавляться суффикс с версией scala. Все библиотеки зависимостей из списка «libraryDependencies» копируются в каталог `.commonlib`. За формирование каталога `.commonlib` отвечают sbt-задания `publishLibDependencies` и `publishDevDependencies`, выполняемые в зависимости от режима сборки проекта автоматически или вручную. ```{attention} При выполнении sbt задачи `publishDevDependencies` в Intellij Idea может выдаваться ошибка вида: ~~~ [error] download error: Caught javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target (sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target) while downloading https://ivy.global-system.ru/ ~~~ ``` Ошибка проверки возникает из-за того, что в хранилище доверенных корневых сертификатов Java нет CA-сертификата промежуточного сервера для let's encrypt. Исправить ошибку можно следующим образом: 1. Добавить сертификат в стандартное хранилище доверенных CA-сертификатов \ Для Java приложений сгенерировать новый CA-сертификат R3 для Let's Encrypt можно с помощью утилиты keytool. Java Keytool — это инструмент командной строки, который может генерировать пары открытый ключ / закрытый ключ и сохранять их в хранилище ключей. Исполняемый файл утилиты распространяется вместе с Java SDK (или JRE) пример использования: ```text keytool -importcert -file mycertfile.pem -keystore cacerts -alias "Alias" ``` Стандартный пароль хранилища: changeit 2. Заменяем хранилище \ `C:\Program Files\Java\jdk[версия]\jre\lib\security\cacerts` файлом из архива `Global3FrameworkStarterKit.zip` ## Первая сборка проекта Когда проект открывается впервые IDE Intellij Idea проиндексирует его состав и выполнит обновление sbt проекта. После этого необходимо выполнить агрегацию библиотек проекта и собрать проект. 1. Дождитесь окончания инициализации проекта и индексации исходного кода 2. Обновите sbt проект ![refreshSBT](../img/idea_sbt_panel.png) 3. Выполните агрегацию библиотек проекта \ Для этого запустите на панели sbt задачу `publishDevDependencies` \ При этом sbt задача просканирует проект на наличие зависимостей и сформирует в корне проекта каталог `.commonlib` со всеми необходимыми библиотеками. ```{attention} При выполнении sbt задачи `publishDevDependencies` в Intellij Idea может выдаваться ошибка вида: ~~~ [error] download error: Caught javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target (sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target) while downloading https://ivy.global-system.ru/ ~~~ ``` Ошибка проверки возникает из-за того, что в хранилище доверенных корневых сертификатов Java нет CA-сертификата промежуточного сервера для let's encrypt. \ Для исправления ошибки замините хранилище `C:\Program Files\Java\jdk\[версия]\jre\lib\security\cacerts` файлом из архива `Global3FrameworkStarterKit.zip` 4. Выполнить сборку проекта: Build | Build Project ## Развертывание первоначальных данных Для генерации начальных данных в БД проекта необходимо провести успешную сборку проекта и запустить утилиту создания таблиц. 1. Если требуется сборка проекта, выполните команду `Build project` \ Пункт меню Intellij Idea: `Build > Build Project` 2. После сборки проекта запустите генерацию таблиц \ В обозревателе проекта Intellij Idea вызовите контекстное меню на корневой директории проекта `application` пункт `External Tolls > Generate tables` \ При этом происходит создание таблиц схемы, установка начальных данных и создается пользователь admin с полными правами(пароль admin) После этого конфигурация готова для разработки. ## Запуск приложения Для запуска и отладки приложения вам необходимо ознакомиться с основными принципами [запуска и отладки в idea](https://www.jetbrains.com/help/idea/starting-the-debugger-session.html) Для отладки проекта: 1. Выберите в выпадающем списке конфигураций запуска `Global 3 SE` \ Данная конфигурация создается автоматически дополнительным плагином. Конфигурация появляется при следующем запуске idea. В случаи если плагин не установлен, конфигурацию для запуска необходимо создать вручную. 2. Выполните Debug `Global 3 SE` 3. Подключитесь к запущенному серверу \ Для этого откройет браузер по адресу `http://localhost:8080/` При этом в консоли будет выводиться лог работы сервера. При запуске не должно быть сообщений с типом `[ERROR]` или стеков ошибок. ## Регистрация При первом запуске система Global Postgres потребует зарегистрировать БД Для регистрации базы данных. 1. Сформируйте файл запроса лицензии \ Для формирования файла запроса лицензии необходимо нажать на кнопку «Сформировать и скачать файл запроса лицензии». 2. Запросите лицензионный файл \ Сформированный файл запроса лицензии вместе с заявкой на регистрацию отправьте по электронной почте контактному лицу ООО «Бизнес-Технологии». В заявке рекомендуется указать имена модулей, которые будут созданы. 3. Зарегистрируйте лицензию \ Для этого в диалоге требования регистрации нажмите на кнопку `Установить лицензионный файл`, и выберете полученный файл в открывшемся диалоге. ## Отладка приложений Для отладки прикладного кода: 1. Откройте файл с кодом для отладки 2. Установите точку остановки на требуемой строке 3. Откройте приложение в браузере и выполните отлаживаемое действие \ Выполнение программы будет остановлено на отмеченной строке. ### Отладка бизнес-логики Для отладки и тестирования кода Dpi/Api-классов можно воспользоваться Unit-тестами. Для этого, в каталоге с тестами соответствующего модуля создайте класс, унаследованный от `ru.bitec.app.gtk.eclipse.api.ApiTest`. Смотрите пример: `ru.bitec.app.cur.Cur_CurrencyTest` ### Перекомпиляция кода без перезапуска сервера При отладке приложений, в большинстве случаев, нет необходимости перезапуска веб-сервера при внесении изменений в код любого модуля проекта Application. Для применения изменений необходимо: 1. Выключите кэш \ Выполните пункт меню `Файл \ Использовать кэш` в отлаживаемом приложении 2. Скомпилируйте изменённый модуль \ `Compile module` в контекстном меню модуля или `Build project` на панели инструментов. В отдельных случаях можно компилировать отдельный класс. 3. Обновите приложение \ В главном меню отлаживаемого приложения выполнить `Файл \ SBT \ Обновить и переоткрыть текущую форму` 4. Повторите отлаживаемое действие. ### Отладка выборки Для отладки пользовательских интерфейсов предусмотрен специальный инструмент `Selection debug window`. Вызвать его можно в любом месте системы с помощью сочетания клавиш `ctrl+alt+shift+W`.