include/sdl/errorqueries.hpp

   1 /*
   2    Copyright (c) 2018-2019 Nokia.
   3
   4    Licensed under the Apache License, Version 2.0 (the "License");
   5    you may not use this file except in compliance with the License.
   6    You may obtain a copy of the License at
   7
   8        http://www.apache.org/licenses/LICENSE-2.0
   9
  10    Unless required by applicable law or agreed to in writing, software
  11    distributed under the License is distributed on an "AS IS" BASIS,
  12    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13    See the License for the specific language governing permissions and
  14    limitations under the License.
  15 */
  16
  17 /*
  18  * This source code is part of the near-RT RIC (RAN Intelligent Controller)
  19  * platform project (RICP).
  20 */
  21
  22 /** @file */
  23
  24 #ifndef SHAREDDATALAYER_ERRORQUERIES_HPP_
  25 #define SHAREDDATALAYER_ERRORQUERIES_HPP_
  26
  27 #include <system_error>
  28
  29 namespace shareddatalayer
  30 {
  31    /** @enum shareddatalayer::Error
  32      * @brief Error constants meant for client error handling implementation.
  33      *
  34      * Certain <code>std::error_code</code>s returned by shareddatalayer can
  35      * be compared against these enum values. If returned error can be compared
  36      * against these values, it is mentioned in the documentation of the
  37      * functionality which returns the <code>std::error_code</code>.
  38      *
  39      * Descriptions of the <code>shareddatalayer::Error</code> values and
  40      * instructions how to handle each value:
  41      *
  42      * <code>shareddatalayer::Error::SUCCESS</code>:<br>
  43      * Request was successfully handled, no error handling needed.
  44      *
  45      * <code>shareddatalayer::Error::NOT_CONNECTED</code>:<br>
  46      * shareddatalayer is not connected to the backend data storage and therefore could not
  47      * deliver the request to the backend data storage. Data in the backend data storage
  48      * has not been altered.<br>
  49      * Client is advised to try the operation again later. If shareddatalayer class,
  50      * from which the error originated, contains <code>waitReadyAsync</code> API, client
  51      * can use <code>waitReadyAsync</code> API to get a notification once shareddatalayer
  52      * is connected to the backend data storage.<br>
  53      * Note that if client receives this error for the first SDL API operation which client does,
  54      * it is advised to modify client implementation so that client waits for <code>waitReadyAsync</code>
  55      * notification before doing any SDL API operations.
  56      *
  57      * <code>shareddatalayer::Error::OPERATION_INTERRUPTED</code>:<br>
  58      * shareddatalayer sent the request to the backend data storage but did not receive a reply from
  59      * the backend data storage. In case of a write type request, data in the backend data storage
  60      * may or may not have been altered.<br>
  61      * Client is advised to try the operation again later. If shareddatalayer class, from which the error originated,
  62      * contains waitReadyAsync API, client can use waitReadyAsync API to get a notification once shareddatalayer is
  63      * connected to the backend data storage.<br>
  64      * When shareddatalayer operations work again, client can choose how to best address the possible loss of consistency.
  65      * Client can re-do all the interrupted writes or read the current data in the backend data storage and update it accordingly.
  66      *
  67      * <code>shareddatalayer::Error::BACKEND_FAILURE</code>:<br>
  68      * shareddatalayer delivered the request to the backend data storage but the backend data storage failed to process the request.
  69      * In case of a write type request, data in the backend data storage may or may not have been altered.<br>
  70      * Client is advised to try the operation again later. If also re-tries are failing client should re-create the used shareddatalayer instance.
  71      * It is possible that the system does not automatically recover from this type of error situations. Therefore client is advised
  72      * to escalate the problem to O&M if operation does not succeed after above mentioned recovery actions.<br>
  73      * When shareddatalayer operations work again, client can choose how to best address the possible loss of consistency
  74      * (see <code>shareddatalayer::Error::OPERATION_INTERRUPTED</code> for possible options).
  75      *
  76      * <code>shareddatalayer::Error::REJECTED_BY_BACKEND</code>:<br>
  77      * shareddatalayer delivered the request to the backend data storage but the backend data storage rejected the request.
  78      * In case of a write type request, data in the backend data storage may or may not have been altered.<br>
  79      * It is likely that same request will fail repeatedly. It is advised to investigate the exact reason for the failure from the logs.
  80      * Reason can be, for example, too many keys in the request or too large data in the request. It is backend specific, what kind of
  81      * request is considered invalid. Redis is the most common backend type, maximum supported request parameters with Redis backend
  82      * are currently by default following:
  83      * maximum amount of keys in request: 524287 keys, maximum key/value size: 512MB.
  84      * If the client request is invalid, client implementation needs to be changed. If the reason for invalid request seems to originate
  85      * from shareddatalayer, contact shareddatalayer support. <br>
  86      * When shareddatalayer operations work again, client can choose how to best address the possible loss of consistency
  87      * (see <code>shareddatalayer::Error::OPERATION_INTERRUPTED</code> for possible options).
  88      *
  89      * <code>shareddatalayer::Error::REJECTED_BY_SDL</code>:<br>
  90      * shareddatalayer could not process the request and therefore did not deliver the request to the backend data storage.
  91      * Data in the backend data storage has not been altered.<br>
  92      * It is likely that same request will fail repeatedly. Reason can be, for example, illegal parameter passed to SDL API function.
  93      * It is advised to investigate the exact reason for the failure, for example, by investigating logs and returned <code>std::error_code</code>.
  94      * If the client request is invalid, client implementation needs to be changed.<br>
  95      */
  96     enum class Error
  97     {
  98         SUCCESS = 0,
  99         NOT_CONNECTED,
 100         OPERATION_INTERRUPTED,
 101         BACKEND_FAILURE,
 102         REJECTED_BY_BACKEND,
 103         REJECTED_BY_SDL
 104     };
 105
 106     /// @private
 107     std::error_condition make_error_condition(shareddatalayer::Error ec);
 108 }
 109
 110 namespace std
 111 {
 112     /// @private
 113     template <>
 114     struct is_error_condition_enum<shareddatalayer::Error> : public true_type { };
 115 }
 116
 117 #endif