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 /** @file */
  18
  19 #ifndef SHAREDDATALAYER_ERRORQUERIES_HPP_
  20 #define SHAREDDATALAYER_ERRORQUERIES_HPP_
  21
  22 #include <system_error>
  23
  24 namespace shareddatalayer
  25 {
  26    /** @enum shareddatalayer::Error
  27      * @brief Error constants meant for client error handling implementation.
  28      *
  29      * Certain <code>std::error_code</code>s returned by shareddatalayer can
  30      * be compared against these enum values. If returned error can be compared
  31      * against these values, it is mentioned in the documentation of the
  32      * functionality which returns the <code>std::error_code</code>.
  33      *
  34      * Descriptions of the <code>shareddatalayer::Error</code> values and
  35      * instructions how to handle each value:
  36      *
  37      * <code>shareddatalayer::Error::SUCCESS</code>:<br>
  38      * Request was successfully handled, no error handling needed.
  39      *
  40      * <code>shareddatalayer::Error::NOT_CONNECTED</code>:<br>
  41      * shareddatalayer is not connected to the backend data storage and therefore could not
  42      * deliver the request to the backend data storage. Data in the backend data storage
  43      * has not been altered.<br>
  44      * Client is advised to try the operation again later. If shareddatalayer class,
  45      * from which the error originated, contains <code>waitReadyAsync</code> API, client
  46      * can use <code>waitReadyAsync</code> API to get a notification once shareddatalayer
  47      * is connected to the backend data storage.<br>
  48      * Note that if client receives this error for the first SDL API operation which client does,
  49      * it is advised to modify client implementation so that client waits for <code>waitReadyAsync</code>
  50      * notification before doing any SDL API operations.
  51      *
  52      * <code>shareddatalayer::Error::OPERATION_INTERRUPTED</code>:<br>
  53      * shareddatalayer sent the request to the backend data storage but did not receive a reply from
  54      * the backend data storage. In case of a write type request, data in the backend data storage
  55      * may or may not have been altered.<br>
  56      * Client is advised to try the operation again later. If shareddatalayer class, from which the error originated,
  57      * contains waitReadyAsync API, client can use waitReadyAsync API to get a notification once shareddatalayer is
  58      * connected to the backend data storage.<br>
  59      * When shareddatalayer operations work again, client can choose how to best address the possible loss of consistency.
  60      * Client can re-do all the interrupted writes or read the current data in the backend data storage and update it accordingly.
  61      *
  62      * <code>shareddatalayer::Error::BACKEND_FAILURE</code>:<br>
  63      * shareddatalayer delivered the request to the backend data storage but the backend data storage failed to process the request.
  64      * In case of a write type request, data in the backend data storage may or may not have been altered.<br>
  65      * Client is advised to try the operation again later. If also re-tries are failing client should re-create the used shareddatalayer instance.
  66      * It is possible that the system does not automatically recover from this type of error situations. Therefore client is advised
  67      * to escalate the problem to O&M if operation does not succeed after above mentioned recovery actions.<br>
  68      * When shareddatalayer operations work again, client can choose how to best address the possible loss of consistency
  69      * (see <code>shareddatalayer::Error::OPERATION_INTERRUPTED</code> for possible options).
  70      *
  71      * <code>shareddatalayer::Error::REJECTED_BY_BACKEND</code>:<br>
  72      * shareddatalayer delivered the request to the backend data storage but the backend data storage rejected the request.
  73      * In case of a write type request, data in the backend data storage may or may not have been altered.<br>
  74      * It is likely that same request will fail repeatedly. It is advised to investigate the exact reason for the failure from the logs.
  75      * 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
  76      * request is considered invalid. Redis is the most common backend type, maximum supported request parameters with Redis backend
  77      * are currently by default following:
  78      * maximum amount of keys in request: 524287 keys, maximum key/value size: 512MB.
  79      * If the client request is invalid, client implementation needs to be changed. If the reason for invalid request seems to originate
  80      * from shareddatalayer, contact shareddatalayer support. <br>
  81      * When shareddatalayer operations work again, client can choose how to best address the possible loss of consistency
  82      * (see <code>shareddatalayer::Error::OPERATION_INTERRUPTED</code> for possible options).
  83      *
  84      * <code>shareddatalayer::Error::REJECTED_BY_SDL</code>:<br>
  85      * shareddatalayer could not process the request and therefore did not deliver the request to the backend data storage.
  86      * Data in the backend data storage has not been altered.<br>
  87      * It is likely that same request will fail repeatedly. Reason can be, for example, illegal parameter passed to SDL API function.
  88      * It is advised to investigate the exact reason for the failure, for example, by investigating logs and returned <code>std::error_code</code>.
  89      * If the client request is invalid, client implementation needs to be changed.<br>
  90      */
  91     enum class Error
  92     {
  93         SUCCESS = 0,
  94         NOT_CONNECTED,
  95         OPERATION_INTERRUPTED,
  96         BACKEND_FAILURE,
  97         REJECTED_BY_BACKEND,
  98         REJECTED_BY_SDL
  99     };
 100
 101     /// @private
 102     std::error_condition make_error_condition(shareddatalayer::Error ec);
 103 }
 104
 105 namespace std
 106 {
 107     /// @private
 108     template <>
 109     struct is_error_condition_enum<shareddatalayer::Error> : public true_type { };
 110 }
 111
 112 #endif