Плагин Apache Camel

Плагин встраивает Apache Camel в ERP и формирует маршруты сообщений из аннотаций на Java- и Kotlin-классах. Основное применение в проекте — получение сообщений из очередей и топиков ActiveMQ, преобразование JSON в типизированные объекты и вызов обработчиков ERP.

Плагин не предоставляет отдельного пользовательского интерфейса. Компоненты и обработчики задаются в глобальной конфигурации ERP.

Текущее состояние

В проекте используются Apache Camel 3.0.0-M2 и ActiveMQ 5.7.0. Несмотря на наличие клиентской библиотеки Kafka в зависимостях, фабрика компонентов плагина поддерживает только ActiveMQ.

Плагин зарегистрирован с id apache-camel. Наличие @From на методе само по себе не включает обработчик: класс обязательно должен быть указан в camel.handler.<n>.class.

Как обрабатывается сообщение

ActiveMQ-компонент получает сообщение из endpoint, указанного в @From.
При наличии @Redelivery к маршруту подключается политика повторной доставки и dead letter queue.
При наличии @Throttle ограничивается скорость обработки.
Тело сообщения преобразуется в тип единственного аргумента метода.
Метод вызывается от имени служебного пользователя ERP.
Если указан @To, возвращённое значение сериализуется и отправляется в выходной endpoint.
После обработки публикуется событие телеметрии со статусом success или failure.

Подробное описание аннотаций и требований к классу приведено в разработке обработчиков.

Включение плагина

В основной конфигурации приложения задаются два параметра:

camel.enabled=1
camel.configId=<id глобальной конфигурации Camel>

camel.enabled: Включает создание CamelContext. По умолчанию плагин выключен.
camel.configId: Id глобальной конфигурации, в которой находятся компоненты и обработчики. По умолчанию -1.

Конфигурацию маршрутов рекомендуется хранить отдельно от основной конфигурации приложения. Не следует полагаться на конкретный id: он может отличаться между стендами. Изменение camel.enabled или camel.configId в локальном properties-файле требует перезапуска приложения.

Компонент ActiveMQ

Компонент объявляется блоком camel.component.<n>.*:

camel.component.1.id=amq
camel.component.1.type=activemq
camel.component.1.url=tcp://broker.example:61616
camel.component.1.login=<login>
camel.component.1.password=<password>

Параметр Обязательный Назначение

Параметр	Обязательный	Назначение
`id`	Да	Имя компонента внутри CamelContext. Оно становится схемой endpoint, например `amq:queue:orders`.
`type`	Да	Тип компонента. Текущее допустимое значение — `activemq`, регистр не важен.
`url`	Да	Broker URL ActiveMQ.
`login`	Да	Пользователь брокера.
`password`	Да	Пароль брокера.

id

Да

Имя компонента внутри CamelContext. Оно становится схемой endpoint, например amq:queue:orders.

type

Да

Тип компонента. Текущее допустимое значение — activemq, регистр не важен.

url

Да

Broker URL ActiveMQ.

login

Да

Пользователь брокера.

password

Да

Пароль брокера.

Компонент создаётся в режиме JMS Client Acknowledge. Если обязательные параметры не заполнены, компонент не регистрируется, а ошибка записывается в журнал. Остальные корректные компоненты и обработчики продолжают инициализироваться.

Конфигурация содержит пароль брокера. Не помещайте реальные реквизиты в документацию, исходный код, сообщения задач и логи диагностики.

Регистрация обработчиков

Каждый класс добавляется отдельной строкой:

camel.handler.1.class=ru.bgcrm.plugin.example.OrderHandler
camel.handler.2.class=ru.bgcrm.dyn.camel.DynamicOrderHandler

Поддерживаются классы ядра и динамические классы из пакета ru.bgcrm.dyn. При запуске плагин:

загружает класс;
создаёт экземпляр через публичный конструктор без аргументов;
находит объявленные в классе методы с @From;
создаёт отдельный Camel route для каждого валидного метода.

Наследованные методы не сканируются, потому что анализируются только методы, объявленные непосредственно в классе. Синтетические методы пропускаются.

Ошибочный класс или обработчик не останавливает регистрацию остальных: ошибка записывается в журнал, после чего инициализация продолжается.

Обработчики в основном коде

В ядре проекта объявлены следующие потребители. Они создают маршруты только тогда, когда их классы присутствуют в camel.handler.* активной конфигурации.

Класс Очередь Назначение

Класс	Очередь	Назначение
`ElasticSearchMessageListener`	`erp.elastic.customer.sync`	Синхронизация контрагента с Elasticsearch.
`FiasAddressHandler`	`erp.fias`	Обработка адресных событий ФИАС.
`ActivationConnectHandler`	`erp.server.connect.activate`	Активация подключения юридического лица.
`SuspensionHandler`	`erp.server.maintenance.suspend`	Приостановка обслуживания.
`PartialSuspensionHandler`	`erp.server.maintenance.partial.suspend`	Частичная приостановка обслуживания.
`ResumeHandler`	`erp.server.maintenance.resuming`	Возобновление обслуживания.
`PartialResumeHandler`	`erp.server.maintenance.partial.resume`	Частичное возобновление обслуживания.
`RelocationHandler`	`erp.server.maintenance.relocate`	Перенос обслуживания.
`TerminationHandler`	`erp.server.maintenance.terminate`	Расторжение договора.

ElasticSearchMessageListener

erp.elastic.customer.sync

Синхронизация контрагента с Elasticsearch.

FiasAddressHandler

erp.fias

Обработка адресных событий ФИАС.

ActivationConnectHandler

erp.server.connect.activate

Активация подключения юридического лица.

SuspensionHandler

erp.server.maintenance.suspend

Приостановка обслуживания.

PartialSuspensionHandler

erp.server.maintenance.partial.suspend

Частичная приостановка обслуживания.

ResumeHandler

erp.server.maintenance.resuming

Возобновление обслуживания.

PartialResumeHandler

erp.server.maintenance.partial.resume

Частичное возобновление обслуживания.

RelocationHandler

erp.server.maintenance.relocate

Перенос обслуживания.

TerminationHandler

erp.server.maintenance.terminate

Расторжение договора.

Дополнительные обработчики могут находиться в динамическом проекте и потому не перечислены в исходном коде ядра.

Жизненный цикл

При запуске приложения плагин выполняет полную инициализацию:

останавливает прежний контекст, если он активен;
создаёт и запускает новый DefaultCamelContext;
регистрирует компоненты;
создаёт маршруты обработчиков.

Полная реинициализация выполняется в двух случаях:

изменена глобальная конфигурация с id из camel.configId;
перекомпилирован динамический класс, который в этот момент присутствует в списке camel.handler.*.

Если camel.enabled выключен, при событии изменения конфигурации активный контекст останавливается. Изменение другой глобальной конфигурации не перезапускает Camel.

Во время реинициализации старый контекст сначала полностью останавливается, поэтому обработка маршрутов временно недоступна. Отдельного «горячего» обновления одного маршрута нет.

Связанные разделы

Ограничения

Поддерживается только ActiveMQ; произвольные Camel-компоненты из конфигурации создать нельзя.
Автоматического поиска обработчиков по classpath нет.
Один метод-обработчик должен иметь ровно один аргумент.
Транзакция ERP вокруг вызова автоматически не создаётся.
Плагин не переносит пользователя или права отправителя сообщения: обработчик выполняется как служебный пользователь.
Конфигурация JMX самим плагином не выполняется. Доступность JMX зависит от настроек JVM и Camel на конкретном стенде.