Errors

Introduction

Exceptions are wildly used in COREmanager libraries. Exceptions enable to easily add error information. Follow the rules below when writing your components:

1. Never add exceptions occurred during internal calls isp_api::InternalCall. It may influence the smooth operation of the system, because some operations may not be completed. If you detected an error and want to try completing the call, send a request once again later. isp_api::RestartRequest.
2. Never trap exceptions without the catch (...) type or throughout the exception throw /** without parameters */;
3. Always sent a language and session in internal and external requests. It will enable you to get error message in a specific language.

Types of exceptions

Exceptions in COREmanager libraries can be classified based on their processing algorithm:

Exceptions mgr_err::Error

Practically all of the exceptions in COREmanager libraries belong to the mgr_err::Error type. It is inherited from std::exception. So that if you to trap all exceptions, you'd better intercept mgr_err::Error or std::exception. In COREmanager we do not use typification of exceptions. First, exceptions may occur in case of remote requests, and their serialization and deserialization sometimes is impossible (local version of COREmanager, receiving an exception from a remote service, may simply not contain a required class of exceptions). Second, usually there is no need in typification of exceptions (99% of all catch is catch(const mgr_err::Error &) or catch(const std::exception &)).

This class contains a stack status when the exception occurs, and the XML-document describing a type of exception. Following is the XML example:

<?xml version="1.0" encoding="UTF-8"?>
<doc>
  <error type="xml" object="xpath" report="yes" lang="ru">
    <param name="object" type="msg" msg="Error in XPath '__value__'">xpath</param>
    <param name="value">bad XPath</param>
    <stack>
      <action level="30" user="root">xmlerror</action>
    </stack>
    <group>An error when working with the XML-document. __object__</group>
    <msg>An error occurred when working with the XML-document. Error in XPath 'bad XPath'</msg>
  </error>
</doc>

Attributes and child nodes of the error node:

external"yes" indicates an exception from a remote service. Such exceptions require no special processing.report"yes" indicates that a report should be sent to software developers. Such exceptions should not be sent to users. If a user does get it, he will be asked to inform developers.helpif specified, an error message will contain a link to documentation. The article name will be taken from the attribute value.typeexclusion type - string in any format. Used for locales.langlocalization language.objectvalue of the object parametervaluevalue of the value parameterthe param nodeexception parameter. It has the following parameters: @name - parameter name, @type - parameter type (must have the "msg" value for localization parameters), @msg - localized value. Parameter's value is taken from the node.the stack nodecall stack isp_api::InternalCall at the time the exception occurs. Each child node action contains the @level and @user attributes, which are user role and username who performed the operation. A function name is specified in the action node.the detail node, group and defaultlocalized description of exception.the msg noselocalized description of the exception.

Locale

Classes of exceptions

Though we do not use typification of exceptions, not all exceptions are processed in the same way. In COREmanager libraries they are classified only on the error node attributes. Groups classified according to processing type are listed below:

Function errors (local errors)such errors are caused by incorrect system settings or invalid parameters. They should provide all the required information to users.Special errorssimilar to the errors described above, however they are processed differently. Example, notconfigured. In the case of the API request (out=xml), this error will return to users in the same way as errors described above. If am error occurs when accessing the panel through web-interface, a user will be asked to provide missing data. This group also include authorization errors. If they occur in the web-interface, a user will be redirected to the registration form.Library errorsthey can be caused by insufficient resources or it can can be algorithmic errors, if a developer uses some library function incorrectly. If such errors occur, a report to developers will be generated (the report attribute).Errors from remote servicesErrors from remote services running on COREmanager. Their xml can be similar to that of any other error. No special processing is required (the external attribute)

Service exceptions

Except for mgr_err::Error COREmanager uses a number of exceptions that are inherited neither form mgr_err::Error no form std::exception. Users should never see such errors/

Assertcritical error. This error class should never occur. If it does occur, any further operation may be useless or dangerous. This type of exceptions is created by the ASSERT macros. As opposed to standard Assert, it will terminate not an application, but the current string. COREmanager will try to roll back all changes made while the process was running.Restartrequire to process the request once again. This type of exceptions is used by the isp_api::RestartRequest function.Skipinforms that there is not need in processing request. A reply to users will look the same as when this exception occurred.

Error localization

When localizing an error, COREmanager is trying to find corresponding messages searching message sections as follows:

1. mgrerror_<error type>
2. All the message sections starting with the last one (the function causing that error). There can be several sections, if the the error occurred while performing an internal call isp_api::InternalCall
3. mgrerror

In those section COREmanager will search for corresponding values of the msg parameters, and the following messages:

1. msg_error_<type>_<object>
2. msg_error_<type>
3. msg_error_unknown

Message (msg_error_<type>_<object> with the highest priority) will be displayed to users.

In that string all the __<name>__ substrings corresponding to msg parameters will be changed into their localized value. Then, all the __<name>__ substrings corresponding to other parameters will be changed as well.

For example, when using database built-in mechanisms, if you failed to add a record into the database because it is already exists, the exists error will display containing names of duplicated fields (coma separated). To localize that error, add the following message: msg_error_exists_<table_name>

А message text may look like: __cols__ with the __value__ value already exists.