Использование ant

Помимо использования IDE основной be4-функционал доступен с помощью ant-таргетов.

Стандартные таргеты

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

• be.validate — валидация проекта (вычитывание всех файлов, базовые проверки на корректность, исполнение всего Freemarker; никаких обращений к базе не делается)
• be.update — инкрементальное обновление схемы, метаданных и локализаций. Если обновление схемы может привести к потере данных, операция будет отклонена. Для принудительного выполнения определите BE4_FORCE_UPDATE=true
• be.meta — инкрементальное обновление метаданных (включая roles, icons, references, page customizations, pages)
• be.locale — инкрементальное обновление локализаций
• be.ddl — инкрементальное обновление схемы. Для принудительного выполнения определите BE4_FORCE_UPDATE=true. Для обновления схемы клонированных таблиц используйте BE4_CLONES=true.
• be.ddl.check — вывод SQL-предложений, которые потребуются для инкрементального обновления схемы. Никаких изменений в базу не вносится. Для учёта клонированных таблиц используйте BE4_CLONES=true.
• setup.db — полное разворачивание базы с нуля (как в BE)
• setup.meta — полное внесение метаданных и локализаций
• setup.just.meta — полное внесение метаданных
• setup.locale — полное внесение локализаций
• setup.adhoc — выполнение одного или нескольких FTL-скриптов из custom steps (передаются параметром -DA_SCRIPT='script1;script2'). Можно запускать скрипты из модуля (-DA_SCRIPT='realty:dictionaries') либо из всех модулей, где такой скрипт есть (-DA_SCRIPT='all:dictionaries')
• main (таргет по умолчанию, можно просто ant) — сборка war
• fast — быстрая сборка, без war - для редеплоя

be.fast

Быстрое обновление уже существующих в базе operation и query

• ant be.fast -DBE4_SKIP_IVY=true -Dfiles="_kkt_" - все operation и query
• ant be.fast -DBE4_SKIP_IVY=true -Dfiles="_kkt_:op" - все operation
• ant be.fast -DBE4_SKIP_IVY=true -Dfiles="_kkt_:query" - все query

Доступны варианты: query, queryRecord, queryCust, op, opRecord, opCust. Без второго параметра обновляется всё.

Только код одной операции:
ant be.fast -DBE4_SKIP_IVY=true -Dfiles="_kkt_:opRecord:Select Kkt"
Несколько Entity:
ant be.fast -DBE4_SKIP_IVY=true -Dfiles="_kkt_;utilityDocuments"

Добавление таргета:

<target name="be.fast" depends="be4_settings">
  <be4.fileFast projectPath="${project.home}" files="${files}" modules="true" />
</target>

Переменные

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

• BE4_DIR — каталог с проектом be4 (без него ничего не заработает)
• BE4_PROFILE — если задано, указывает профиль соединения к базе данных (из connectionProfiles.*.yaml), который необходимо использовать.
• BE4_LOG_DIR — если задано, данный каталог будет использован для логирования BE4-операций.
• BE4_DEBUG — если "true", будет выводиться дополнительная отладочная информация в stderr.
• BE4_FORCE_UPDATE — если "true", будут выполняться потенциально опасные изменения в схеме базы данных (которые могут привести к потере пользовательских данных).
• BE4_CLONES — если "true", изменения схемы коснутся также клонированных таблиц (у которых численный суффикс добавлен к имени таблицы).
• BE4_UNLOCK_PROTECTED_PROFILE — если "true", защищённый (protected) профиль соединения будет использоваться без дополнительных подтверждений.

• BE4_<имя_модуля> — если true, то будут использованы метаданные из BE4-модуля (BE4-модуль должен существовать), иначе — из старого BE-модуля с тем же именем.

Только с таргетом be.validate:

• BE4_SKIP_VALIDATION=true — если задано, пропустить собственно валидацию (но прочие команды из списка ниже будут выполняться).
• BE4_RDBMS=mysql/postgres/oracle/db2/sqlserver/m4 — если задано, валидация будет выполняться с использованием соответствующей СУБД (это может повлиять на выполнение условных секций в FTL, результат разворачивания макросов, включения extras и т. д.).
• BE4_CHECK_QUERY="entity.query" — если задано, текст указанного запроса после выполнения FTL будет выведен на экран). Если указана фиктивная BE4_RDBMS=m4, на место СУБД-специфичных FTL-функций будут подставлены соответствующие m4-функции (может пригодиться для обратного портирования кода в m4).
• BE4_CHECK_DDL=entity — если задано, DDL, необходимый для создания указанной сущности будет выведен на экран. Если указана фиктивная BE4_RDBMS=m4, будет сгенерирован соответствующий m4-код (может пригодиться для обратного портирования кода в m4).
• BE4_CHECK_ROLES=true — если задано, на экран будет выведен список ролей проекта, действующий в данных условиях. Может пригодиться, если часть ролей устанавливается условно через extras и хочется проверить, правильно ли отработали условия.
• BE4_CREATE_PROFILE_PROPERTIES=<file_path> — создаёт файл properties со свойствами профиля соединения и проекта, который может пригодиться для старой системы тестирования.
• BE4_SAVE=true — если задано, проект будет пересохранён (только основной проект, без учёта подключенных модулей) с помощью той же процедуры, как при сохранении через Eclipse. Могут быть отсортированы или переформатированы некоторые элементы проекта.

Задачи

При редактировании ant-скриптов можно использовать следующие задачи (tasks):

• be4.db — создание базы по BE4-проекту. Параметры:

• modules: если true, будут использованы BE4-модули

• be4.meta — синхронизация. Параметры:

• modules: если true, будут использованы BE4-модули
• mode: режим синхронизации (all, meta, locale, ddl, ddl_clones, security). Если установлено -DBE4_CLONES=true, то режим ddl превращается сам в ddl_clones (добавляется обновление схемы клонированных таблиц).

• be4.data — выполнение скрипта или набора скриптов. Параметры:

• scriptName: имена скриптов через точку с запятой. Можно написать moduleName:scriptName для выполнения скрипта из модуля, либо all:scriptName для выполнения скрипта с таким именем из всех модулей.

• be4.validate — валидировать BE4-проект и (для немодульного проекта) заполнить свойства ANT из модели

• modules: если true, будут подключены BE4-модули. Рекомендуется ставить в true всегда кроме каких-то частных случаев, когда важна производительность.

• be4.fileFast — Быстрое обновление уже существующих в базе operation и query с кастомизациями

• be4.tools — дополнительный инструментарий BE4.

У всех задач есть общие параметры:

• projectPath (обязательно) — путь к проекту
• logDir — каталог для логирования (переопределяет переменную BE4_LOG_DIR)
• useMeta — экспериментальная опция: использовать базовые beanexplorer-метаданные из YAML-проекта beanexplorer_meta без вычитывания базы инициализированной через m4.

Инструментарий

Для технических операций имеется специальная ant-задача be4.tools. По умолчанию эта задача не соответствует никакому ant-таргету. Если она требуется, можно создать таргет, например, так:

<target name="be.tools" depends="be4_settings"><be4.tools projectPath="${project.home}"/></target>

Для пользования инструментами необходимо задавать дополнительные свойства:

• BE4_DUMP_TABLES="таблица1,таблица2,..." — сдампить из базы соответствующей текущему connection-profile заданные таблицы в новый yaml-проект (будет создан подкаталог yamlDump в текущем каталоге). Может пригодиться для создания болванки при переносе таблиц из m4 в yaml. Пример:

ant be.tools -DBE4_PROFILE=foo -DBE4_DUMP_TABLES=users,queries,operations

В дампе присутствуют все представления, операции и схемы указанных сущностей, а также сообщения локализации с таким же entityName. Кроме того, содерижмое сущностей с типом dictionary (в которых менее 10000 строк) дампится в ftl-скрипты, которые автоматически подключены из dictionaries.ftl.

• BE4_SQL_CONSOLE=true — включить FTL/SQL-консоль в контексте текущего проекта и выбранного профиля соединения. Далее можно в интерактивном режиме вводить FTL, который будет преобразовываться в SQL и выполняться. Если просто хочется выполнить FTL, можно начинать с комментария //. К примеру, если хотим проверить как раскрывается макрос:

Enter FTL/SQL (use 'quit' to exit):
//${CRM_AGE('date', 'date2')}
SQL> //            CAST(EXTRACT(YEAR FROM AGE(date2,date)) AS INTEGER)

Если комментарий не использовать, запрос выполнится (выводится до 20 строк результата):

Enter FTL/SQL (use 'quit' to exit):
SELECT * FROM entities LIMIT 5;
SQL> SELECT * FROM entities LIMIT 5;
| name                  | displayname           | primarykeycolumn | type              | entitymodel | origin       |
|-----------------------|-----------------------|------------------|-------------------|-------------|--------------|
| operations_per_status | operations_per_status | ID               | metadata          | null        | beanexplorer |
| jsprograms            | jsprograms            | publicID         | metadata          | null        | beanexplorer |
| operationExtension    | operationExtension    | ID               | metadata          | null        | beanexplorer |
| pageCustomisation     | pageCustomisation     | ID               | metadata          | null        | beanexplorer |
| icons                 | Icons                 | ID               | genericCollection | null        | beanexplorer |

Для компиляции самого BE4 (в объёме необходимом для последующего использования вышеуказанных ant-таргетов) необходимо набрать ant в каталоге be4/src. Не требуется никаких внешних зависимостей.

Использование вне приложений

Следующие цели можно запускать без какого-либо приложения, т.е. досаточно просто зайти в папку be4/src и написать "ant someTarget":

• wizard — позволяет генерировать новые BE4 приложения. Функционал аналогичен функционалу создания нового приложения в BEclipse (File → New → Project → BeanExplorer → BeanExplorer Project), однако все данные вводятся в консоли, а не в GUI.

Debug и тестирование

For Java 1.5 and later:

export ANT_OPTS=-agentlib:jdwp=transport=dt_socket,address=5005,server=y,suspend=y

Run your Ant script and then attach to port 5005 with your debugger.

Для тестирования, можно использовать mvn install, временно подправив конфиг в (be4/src/build.xml): (найти место по этой строке)

for development <ivy:retrieve pattern="${be4.basedir}/pom/target/[artifact]-[revision].[ext]" type="jar,bundle" log="quiet" setId="ivy-deps"/>