.. _solution:

Решение
===================

Совокупность объектов сервера приложений, объединяющая в себе ресурсы, необходимые для выполнения :term:`прикладного кода<Прикладной код>` решения.

Сервер приложений может запускать несколько решений одновременно. Количество решений ограничивается только объёмом
потребляемой Java-машиной памяти и нагрузкой на ЦП.

.. seealso::
    :java:type:`ru.bitec.gtk.core.CoreSolution`

.. _solution_image:

Образ решения
---------------------
Структура каталогов на диске, содержащая: код, метаданные, библиотеки зависимостей и ресурсы :term:`прикладных модулей<Прикладной модуль>`.

Иерархия загрузчиков классов
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Для каждого образа решения сервером создаётся иерархия загрузчиков классов.

.. code-block::

  CommonClassLoader
        ^
        |
  EntityClassLoader
        ^
        |
  SbtClassLoader

.. note::
    До версии AS 1.22 ms7 родителем для SbtClassLoader являлся CommonClassLoader.

- `CommonClassLoader` - загрузчик классов общих библиотек и низкоуровневых системных модулей (из подкаталогов с именами,
  начинающимися с '.'(точка)).
- `EntityClassLoader` - загрузчик классов бизнес-сущностей (POJO), используемых инфраструктурой JPA (EclipseLink) при
  сериализации/десериализации объектов из/в БД.
- `SbtClassLoader` - загрузчик классов прикладных модулей.

.. note::
    Разделение кода решения на несколько загрузчиков классов реализовано для возможности частичной перезагрузки кода.
    В режиме разработки, когда код решения может изменяться разработчиком несколько раз за минуту, в большинстве
    случаев, нет необходимости перезагружать инфраструктуру ORM EclipseLink и общие библиотеки зависимостей.


Режимы загрузки классов
~~~~~~~~~~~~~~~~~~~~~~~~~~

Загрузка кода образа решения может производиться в двух режимах:

- Эксплуатация (Jar)
- Разработка (Dev)

.. seealso::
    :xsd:class:`Configuration.Sbts.Sbt.SourceMode`


Режим эксплуатации
````````````````````
В промышленном режиме, решение загружает классы и ресурсы из структуры каталогов содержащей jar-файлы.

Структура каталогов образа решения
......................................

.. code-block::

    {G3_HOME}
    └── application
      └── FooProject
        ├── .commonlib
        | └── *.jar
        ├── .gtkjpa
        | └── gtkgpa-1.0.0.jar
        ├── btk
        | └── btk-1.0.0.jar
        ├── gtk
        | └── gtk-1.0.0.jar
        ├── bs
        | └── bs-1.0.0.jar
        └── solution.md5

Каждый подкаталог в ``{G3_HOME}/application/FooProject``, кроме ``.commonlib``, считается каталогом модуля.

При запуске решения, содержимое каталога ``{G3_HOME}/application/FooProject`` полностью копируется в каталог
с уникальным авто-формируемым именем. Путь к корню каталогов указывается в xml-конфигурации сервера
:xsd:attr:`Configuration.Sbts.Sbt.binaryFolder`.

.. note::
    Копирование jar-файлов в каталог с уникальным именем необходимо для возможности горячей перезагрузки прикладного кода,
    после внесения изменений в код и формирования новых jar-файлов. :java:ref:`Загрузчик классов<java.net.URLClassLoader>` блокирует
    jar-файлы на всё время своего существования, что мешает обновлению jar-файлов в текущем каталоге.

MD5-хэш сумма образа
......................................
MD5-хэш сумма образа считывается сервером приложений из файла ``solution.md5``. MD5-хэш, при наличии файла, выводится
в информации о образах решений используемых сервером.

.. seealso:: :ref:`SSH команды <ssh_commands>`

Блокировка дистрибутива образа
......................................
Для установки блокировки необходимо создать файл ``solution.lock`` в каталоге с дистрибутивом образа решения.

Блокировка каталога с дистрибутивом образа необходима для предотвращения попыток загрузки образа сервером приложений,
в момент обновления содержимого каталога. Перед началом копирования файлов из каталога с дистрибутивом в рабочий каталог,
сервер приложений проверяет существование файл ``solution.lock``. Если файл существует, сервер приложений выбрасывает
исключение и прерывает загрузку образа.

Режим разработки
````````````````````
В режиме разработки, решение загружает классы и ресурсы из структуры каталогов прикладного проекта в среде разработки IDEA.
Это позволяет не выполнять дополнительных копирований бинарных файлов и не формировать jar-артефакты прикладных модулей,
что сокращает время запуска отладки проекта и перезагрузки исполняемого кода, после правки и компиляции исходного кода.

Структура каталогов образа решения
......................................

.. code-block::

    FooProject
    └── application
      ├── build
      | └── lib
      |   ├── .commonlib
      |   | └── *.jar
      |   ├── .persistentLib
      |   | └── gtkgpa-1.0.0.jar
      |   └── appLib
      |     ├── btk-1.0.0.jar
      |     └── gtk-1.0.0.jar
      └── bs
        └── target
          └── scala-2.13
            └── classes

В ``CommonClassLoader`` загружаются:

- ``build/lib/.commonlib/*.jar``
- ``build/lib/.persistentLib/*.jar``

В ``SbtClassLoader`` загружаются:

- ``build/lib/appLib/*.jar``
- ``bs/target/scala-2.13/classes``

.. note::
    В схеме, в качестве прикладного модуля, указан ``bs``. В реальных проектах, подобных каталогов с кодом модулей
    неограниченное множество.

.. versionchanged:: 1.19.0_rc16 Появился подкаталог ``build/lib``, в который переместился каталог общих библиотек `.commonlib`
    и добавились каталоги с предварительно скомпилированными jar-файлами прикладных модулей, от которых зависит код
    модулей проекта решения.

.. attention::
    Если в проекте отсутствует каталог ``build/lib``, производится попытка загрузки прикладного кода из каталогов с
    устаревшей структурой.

Устаревшая структура
......................................

.. code-block::

    FooProject
    └── application
      ├── .commonlib
      | └── *.jar
      ├── .gtkjpa
      | └── target
      |   └── scala-2.13
      |     └── classes
      ├── btk
      | └── target
      |   └── scala-2.13
      |     └── classes
      ├── gtk
      | └── target
      |   └── scala-2.13
      |     └── classes
      └── bs
        └── target
          └── scala-2.13
            └── classes

В ``CommonClassLoader`` загружаются:

- ``.commonlib/*.jar``
- ``.gtkjpa/target/scala-2.13/classes``

В ``SbtClassLoader`` загружаются:

- ``btk/target/scala-2.13/classes``
- ``gtk/target/scala-2.13/classes``
- ``bs/target/scala-2.13/classes``