Maven plugin

В проектах на be5 определены следующие mavenant-таргеты:

• be5:validate — валидация проекта (вычитывание всех файлов, базовые проверки на корректность, исполнение всего Freemarker; никаких обращений к базе не делается).
• be5:create-db — создает все таблицы базы данных (включая модули), выполняет скрипты (Pre-db.ftl, Post-db.ftl).
• be5:sync — инкрементальное обновление схемы базы данных. По умолчанию - выводит DDL, который будет использоваться для обновления структуры таблиц, удаления и добавления таблиц. Для принудительного выполнения определите BE5_FORCE_UPDATE=true. Смотри другие опции ниже.
• be5:data — выполнение скрипта по имени переданного в параметре BE5_SCRIPT. По умолчанию 'data'
• be5:generate-doc — автоматически генерирует документацию для Sphynx/ReadTheDocs (см. описание ниже).

Переменные

Имеются следующие BE5-специфичные переменные:

Параметр 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
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:sync
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.
be5:generate-doc
BE5_DOC_PATH	String	путь, куда будет сгенерирована документация

Примеры

mvn be5:sync -DBE5_FORCE_UPDATE=true

mvn be5:data -DBE5_SCRIPT="test"

Автоматическая генерация документации

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

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

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

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 Такие файлы предназначены для включения в страницы документации:

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