# Начало работы с фреймворком
## Требования к аппаратному обеспечению рабочего места разработчика
|Характеристика сервера|Рекомендуемые параметры|
|-|-|
| ОС | 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`.