entaxy-public/documentation/core/exception/Centralized-error-handler.adoc

Централизованный обработчик ошибок для формирования кодов ошибок, их синхронного возврата клиенту и для асинхронного дублирования более подробного описания ошибки для клиента и для Центральной Базы Интеграции.

image::Error-handling-Scheme.jpg[]

= Установка и настройка

Установка модуля происходит через фичу:

* _feature:install error-handler_

Фича включена в общий установочный скрипт и будет устанавливаться вместе с остальными модулями. Во время установки фичи в караф копируются файлы конфигурации:

* _ru.entaxy.esb.error.cfg (основная конфигурация)_
* _ru.entaxy.esb.error.code.cfg (справочник исключений с маппингом на коды ошибок)_
* _ru.entaxy.esb.error.text.cfg (справочник кодов ошибок с маппингом на текстовые сообщения)_

Есть возможность настройки маппинга уровней журналирования через файл конфигурации ru.entaxy.esb.error.severity.cfg.

* _ru.entaxy.esb.error.cfg (основная конфигурация)_

[source,properties]
----
# асинхронный пакет с ошибкой отправляется от имени:
# false - системы, вызвавшей ошибку в шине
# true  - шины (система с идентификатором "-1")
ru.entaxy.esb.error.bus.always_at_source=false

# асинхронный пакет с ошибкой в поле description содержит:
# false - сообщение из маппинга в файле ru.entaxy.esb.error.text.cfg
# true  - содержит сообщение, сохранённое в исключении
ru.entaxy.esb.error.description.exception_message=true

# имя очереди для отправки пакета с ошибкой при недоступности системы, указанной в свойстве ru.entaxy.esb.error.system.name
ru.entaxy.esb.error.queue.name=error

# имя системы для отправки пакета с ошибкой, подразумевается система ЦБИ
ru.entaxy.esb.error.system.name=error

# true - включает в пакет с ошибкой весь stacktrace исключения
ru.entaxy.esb.error.stacktrace.show=true

# свойство автоматического запуска тестового маршрута, который при старте модуля бросает исключение java.lang.IllegalArgumentException: Test exception thrown
ru.entaxy.esb.error.test-route.startup=false
----

* _ru.entaxy.esb.error.code.cfg (справочник исключений с маппингом на коды ошибок)_

Справочник содержит соответствие имён классов исключений и _http_ кодов ошибок. И будет наполняться по мере использования шины в разных ситуациях. Для исключения, имя которого ещё не указано в этом файле, будет возвращаться _http_ код _520 (Unknown Error)._

[source,properties]
----
DefaultException=520
com.ctc.wstx.exc.WstxParsingException=400
java.security.AccessControlException=403
javax.ws.rs.ForbiddenException=403
ru.onec.esb.system.common.exception.ConnectorNotFound=424
ru.onec.esb.system.common.exception.DefaultException=520
ru.onec.esb.system.common.exception.ProfileNotFound=424
# и т.д.
----

* _ru.entaxy.esb.error.text.cfg (справочник кодов ошибок с маппингом на текстовые сообщения)_

Если в основной конфигурации свойство _ru.entaxy.esb.error.description.exception_message_ установлено в _false_, то описание ошибки отправляется из этого файла в соответствие с кодом _http_ ошибки.

[source,properties]
----
# 1xx: Informational
# 2xx: Success
200=OK

# 3xx: Redirection
# 4xx: Client Error
400=Bad Request
403=Forbidden
424=Failed Dependency

# 5xx: Server Error
520=Unknown Error
# и т.д.
----

=== Подключение обработчика ошибок

Для подключения обработчика ошибок к маршрутам какого-либо модуля необходимо выполнить следующие шаги:

. Добавить в модуль обработки ошибок в директорию _src/main/resources/xslt/operation_ новый _xslt_ для формирования ответа с ошибкой. Файл должен называться по имени операции, для которой будет формироваться ответ. Например _sendToJMS.xsl_.
. Добавить в _camelContext_ аттрибут _errorHandlerRef="commonErrorHandler"_ и внутри зарегистрировать обработчик и политику повторной доставки:

[source,xml]
----
<camelContext id="soap-service-endpoints-camel-context"
xmlns="http://camel.apache.org/schema/blueprint"
errorHandlerRef="commonErrorHandler" handleFault="true">

    <errorHandler id="commonErrorHandler" redeliveryPolicyRef="noRedelivery"
                  type="DeadLetterChannel" deadLetterUri="direct-vm:commonErrorEndpoint"/>
    <redeliveryPolicyProfile id="noRedelivery" disableRedelivery="true" />
    <!-- any content -->
</camelContext>
----

Для контекстов, содержащих конечные точки _cxf_, необходимо:

через _pom.xml_ импортировать интерцептор для перехвата ошибок (_SoapFault_)

[source,xml]
----
<bundle.osgi.import.pkg>
    ru.onec.esb.system.core.common.error.handler.interceptor,
    ...
</bundle.osgi.import.pkg>
----

добавить интерцептор в _cxfEndpoint_ и _bean_ с указанием в первом аргументе идентификатора _camelContext_

[source,xml]
----
    <camelcxf:cxfEndpoint id="soap-proxy" ...>
        <!-- any properties and interceptors -->
        <camelcxf:outFaultInterceptors>
            <ref component-id="handleOutFaultInterceptor"/>
        </camelcxf:outFaultInterceptors>
    </camelcxf:cxfEndpoint>

    <bean id="handleOutFaultInterceptor" class="ru.onec.esb.system.core.common.error.handler.interceptor.HandleOutFaultInterceptor">
        <argument ref="soap-service-endpoints-camel-context"/>
        <argument value="direct:error_from_cxf"/>
    </bean>
----

в _camelContext_ добавить маршрут

[source,xml]
----
<route id="error_from_cxf">
    <from uri="direct:error_from_cxf"/>
    <log message="cxf message: ${body}" loggingLevel="DEBUG"/>
    <log message="headers: ${headers}\n" loggingLevel="DEBUG"/>
    <to uri="direct-vm:cxfErrorEndpoint"/>
</route>
----