initial public commit

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

@@ -0,0 +1,144 @@
+Централизованный обработчик ошибок для формирования кодов ошибок, их синхронного возврата клиенту и для асинхронного дублирования более подробного описания ошибки для клиента и для Центральной Базы Интеграции.
+
+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>
+----
+
+

documentation/core/exception/Error-description.adoc

@@ -0,0 +1,31 @@
+= Использование обработчика ошибок
+
+Для централизованной обработки ошибок будем использовать “процессор” зарегистрированный через _<camelContext errorHandlerRef="...”>_. В частных случаях допустимо использование _try …​ catch …​ finally_.
+_(https://camel.apache.org/manual/latest/error-handler.html)_
+
+Кроме возврата ошибок вызывающей стороне, необходимо дублировать ошибки в JMS очередь с возможностью их просмотра из веб-консоли Артемиса.
+
+=== Классификация ошибок
+
+_Бизнесовые ошибки:_ отсутствие обязательных полей, превышение длины поля и другие нарушения ожиданий принимающей стороны.
+
+_Серверные ошибки:_ NPE и другие ошибки времени выполнения.
+
+_Сервис не доступен:_ конечная точка не отвечает и не принимает входящие соединения.
+
+При этом ошибки могут быть “восстанавливаемыми” - с возможностью успешной обработки повторного запроса, использующего изменённые данные или другие точки доступа,  и “не восстанавливаемыми” - у клиента нет возможности обойти причины ошибки для выбранного сервиса.
+
+=== Обёртка для ошибок
+
+Ошибки удобно обрабатывать используя дополнительную информацию, которую необходимо передавать вместе с ошибкой:
+
+* _Timestamp_: время возникновения ошибки;
+* _Error Code_: код ошибки для удобства автоматизированной обработки ошибок;
+* _Error Text_: описание возникающей ошибки, допустимо выводить вместе со стектрейсом;
+* _Severity Level_: уровень журналирования ошибки;
+* _Notification_: в случае необходимости уведомлений об ошибке поле должно содержать адрес или список адресов систем/пользователей для оповещения;
+* _Retry_: информация о возможности повторной отправки сообщения;
+
+_Uuid_ и _id_ сообщения
+
+