Задачи maven
************

Для работы с be5 проектами создан специальный maven-be5 плагин,
в котором определены специальные задачи.

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

 * переменные в коммандной строке
 * xml-тэги в pom.xml

Общие переменные
================

.. list-table::
   :header-rows: 1

   * - Параметр

       XML тэг
     - Тип

       значение по умолчанию
     - Описание
   * - BE5_PROJECT_PATH
       
       <projectPath>
     - File 
       
       ./
     - путь к каталогу с проектом be5
   * - BE5_LOG_PATH
       
       <logPath>
     - File
     - путь к каталогу с проектом be5
   * - BE5_DEBUG  
   
       <debug>
     - boolean
       
       false
     - если "true", будет выводиться дополнительная отладочная информация в stderr
   * - BE5_UNLOCK_PROTECTED_PROFILE
       
       <unlockProtectedProfile>
     - boolean
       
       false
     - если "true", защищённый (protected) профиль соединения будет использоваться без дополнительных подтверждений


be5:validate
============
Валидация проекта - вычитывание всех файлов, базовые проверки на корректность, исполнение всего Freemarker, 
никаких обращений к базе не делается.

.. list-table::
   :header-rows: 1

   * - Параметр
   
       XML тэг
     - Тип
     
       значение по умолчанию
     - Описание
   * - BE5_SKIP_VALIDATION
   
       <skipValidation>
     - boolean
     
       false
     - если "true", пропустить собственно валидацию (но прочие команды из списка ниже будут выполняться)
   * - BE5_RDBMS
   
       <rdbmsName>
     - String
     - валидация будет выполняться с использованием соответствующей СУБД.
       Это может повлиять на выполнение условных секций в FTL, результат разворачивания макросов, включения extras и т. д.
       
       
       Возможные значения: mysql/postgres/oracle/db2/sqlserver
   * - BE5_CHECK_QUERY
   
       <queryPath>
     - String
     - Формат - entity.query. Если задано, текст указанного запроса после выполнения FTL будет выведен на экран
   * - BE5_CHECK_ROLES
   
       <checkRoles>
     - boolean
     
       false
     - если "true", на экран будет выведен список ролей проекта, действующий в данных условиях. 
       Может пригодиться, если часть ролей устанавливается условно через extras и хочется проверить, правильно ли отработали условия
   * - BE5_CHECK_DDL
   
       <ddlPath>
     - String
     - entity. Если задано, DDL, необходимый для создания указанной сущности, будет выведен на экран
   * - BE5_SAVE_PROJECT
   
       <saveProject>
     - boolean
     
       false
     - если "true", проект будет пересохранён (только основной проект, без учёта подключенных модулей). 
       Могут быть отсортированы или переформатированы некоторые элементы проекта

be5:create-db
=============
Создает все таблицы базы данных (включая модули), выполняет скрипты (Pre-db.ftl, Post-db.ftl).


be5:sync
========
Инкрементальное обновление схемы базы данных. 
По умолчанию выводит DDL, который будет использоваться для обновления структуры таблиц, удаления и добавления таблиц. 
Для принудительного выполнения определите BE5_FORCE_UPDATE=true. Смотри другие опции ниже.

.. list-table::
   :header-rows: 1

   * - Параметр
   
       XML тэг
     - Тип
       
       значение по умолчанию
     - Описание
   * - BE5_FORCE_UPDATE
   
       <forceUpdate>
     - boolean
     
       false
     - "false" — сгенерированный DDL для обновления базы данных будет выведен на экран без изменения самой структуры базы данных.
     
       "true" — сгенерированный DDL будет выполнен, что может привести к потере пользовательских данных.
   * - BE5_UPDATE_CLONES
   
       <updateClones>
     - boolean
     
       false
     - если "true", будет сгенерирован DDL для изменения структуры клонированных таблиц 
       (у которых численный суффикс добавлен к имени таблицы)
   * - BE5_DELETE_CLONES
   
       <deleteClones>
     - boolean
     
       false
     - если "true", будет сгенерирован DDL для удаления всех клонированных таблиц 
       (у которых численный суффикс добавлен к имени таблицы)
   * - BE5_DELETE_UNUSED_TABLES
   
       <deleteUnusedTables>
     - boolean
     
       false
     - если "true", будет сгенерирован DDL для удаления всех неиспользуемых таблиц.
       Неиспользуемые таблицы — те таблицы, которые: не перечислены в проекте; не являются клонами перечисленных таблиц.
       Как правило, неиспользуемые таблицы могут обнаруживаться, когда из проекта удаляется entity.

Пример:

.. code-block:: bash

   mvn be5:sync -DBE5_FORCE_UPDATE=true
   
be5:data
========
Выполнение скрипта по имени, переданному в параметре BE5_SCRIPT. По умолчанию — "data".

Пример:

.. code-block:: bash

   mvn be5:data -DBE5_SCRIPT="test"




be5:generate-doc
================
Автоматически генерирует документацию для Sphynx/ReadTheDocs.

.. list-table::
   :header-rows: 1

   * - Параметр
   
       XML тэг
     - Тип
     
       значение по умолчанию
     - Описание
   * - BE5_DOC_PATH
     - String
     - путь, куда будет сгенерирована документация


Предполагается следующий сценарий использования:

 * существует готовый проект Sphynx/ReadTheDocs (dir/projectDocs). 
   Пример проекта: https://github.com/DevelopmentOnTheEdge/be5/tree/master/maven/src/test/resources/doc
 * исходные rst-файлы, написанные разработчиком, лежат в папке dir/projectDocs/source
 * из директории проекта, для которого генерируется документация, запускаем:

  .. code-block:: bash

     mvn be5:generate-doc BE5_DOC_PATH=dir/projectDocs/source

 * Документация будет сгенерирована в папку dir/projectDocs/source/be5
 * В ней будет две поддиректории:
   * tables — файлы для всех таблиц. 
   Кроме того, там лежит файл ``__tables.rst``, который содержит список всех таблиц и который можно использовать 
   как оглавление для структуры базы данных.
   * diagrams — ER-диаграммы в формате PlantUML (см. ниже)

Для настройки генерации диаграмм используется файл dir/projectDocs/source/.be5.yaml.

В нём указываются:
 * список диаграмм, которые нужно сгенерировать
 * таблицы, которые должны войти в каждую диаграмму
 * таблицы, которые можно включать в другие страницы документации

Пример .be5.yaml
----------------
.. code-block:: yaml

   diagrams:                           # блок для спецификации диаграмм, содержит массив
     - diagram_1:                      # название диаграммы, будет сгенерирован файл dir/projectDocs/source/be5/diagrams/diagram_1.puml
         tables: [comments, entities]  # список таблиц, которые будут включены в диаграмму.

   nested_tables: [comments, entities] # список таблиц, для которых будут сгенерированы файлы для включения в отдельные страницы

nested_tables — это отдельные файлы, генерируемые в dir/projectDocs/source/be5/tables/table_name.rstincl.
Такие файлы предназначены для включения в страницы документации:

.. code-block:: rst

   .. include:: be5/tables/table_name.rstincl