X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;f=include%2Fsdl%2Fsyncstorage.hpp;h=80f90d00f53cbc345332dfcfe936582198d7f7a9;hb=63869e10ac4d8572238989e1b582c0314da91f9c;hp=409207f29537ae10f2d5f8d2b8c7ed299611bc1c;hpb=faf9fc79e58fa4ace9b0ef317b741afb2c1a8abe;p=ric-plt%2Fsdl.git

diff --git a/include/sdl/syncstorage.hpp b/include/sdl/syncstorage.hpp
index 409207f..80f90d0 100644
--- a/include/sdl/syncstorage.hpp
+++ b/include/sdl/syncstorage.hpp
@@ -75,6 +75,43 @@ namespace shareddatalayer
 
         using DataMap = std::map<Key, Data>;
 
+        /**
+         * Wait for the service to become ready to serve. There is typically a waiting period
+         * when product cluster is brought up (deploying container orchestrated service,
+         * container restart etc.). The function can be called and used to synchronize the
+         * application startup with the readiness of the underlying data storage.
+         *
+         * This function can also be used if SDL returns an error indicating connection cut
+         * to backend data storage. In that situation client can use this function to get an
+         * indication when SDL is again ready to serve. SDL error code documentation indicates
+         * the error codes for which the usage of this function is applicable.
+         *
+         * Exceptions thrown (excluding standard exceptions such as std::bad_alloc) are all
+         * derived from shareddatalayer::Exception base class. Client can catch only that
+         * exception if separate handling for different shareddatalayer error situations is not
+         * needed.
+         *
+         * @param ns Namespace under which this operation is targeted. As it is possible to
+         *           use different DB backend instances for namespaces, it is necessary to
+         *           provide namespace for this call to test the DB backend readiness of that
+         *           particular namespace. it is recommended to call this always when starting
+         *           to use new namespace.
+         *
+         * @param timeout Timeout value after which readiness waiting will be expired in case
+         *                the SDL service won't come up. It is recommended to use rather long
+         *                timeout value to have enough time for a system to recover for example
+         *                from restart scenarios. Suitable timeout value depends greatly from
+         *                the environment itself. As an example an application could use 10
+         *                seconds timeout value and have a loop what does a re-try every time
+         *                when previous waitReady call has failed. On a side note, timeout
+         *                value 0 means that readiness is waited interminable.
+         *
+         * @throw NotConnected if shareddatalayer is not connected to the backend data storage.
+         * @throw RejectedBySdl if SDL rejects the request.
+         * @throw BackendError if the backend data storage fails to process the request.
+         */
+        virtual void waitReady(const Namespace& ns, const std::chrono::steady_clock::duration& timeout) = 0;
+
         /**
          * Write data to shared data layer storage. Writing is done atomically, i.e. either
          * all succeeds or all fails.
@@ -230,9 +267,37 @@ namespace shareddatalayer
          * @throw OperationInterrupted if shareddatalayer does not receive a reply from the backend data storage.
          * @throw InvalidNamespace if given namespace does not meet the namespace format restrictions.
          */
+        [[deprecated("Use listKeys() instead.")]]
         virtual Keys findKeys(const Namespace& ns,
                               const std::string& keyPrefix) = 0;
 
+        /**
+         * List all keys matching search glob-style pattern under the namespace.
+         *
+         * Supported glob-style patterns:
+         *   h?llo matches hello, hallo and hxllo
+         *   h*llo matches hllo and heeeello
+         *   h[ae]llo matches hello and hallo, but not hillo
+         *   h[^e]llo matches hallo, hbllo, ... but not hello
+         *   h[a-b]llo matches hallo and hbllo
+         *
+         * The \ escapes character(s) in key search pattern and those will be treated as a normal
+         * character(s):
+         *   h\[?llo\* matches h[ello* and h[allo*
+         *
+         * @param ns Namespace under which this operation is targeted.
+         * @param pattern Find keys matching a given glob-style pattern.
+         *
+         * @return Found keys.
+         *
+         * @throw BackendError if the backend data storage fails to process the request.
+         * @throw NotConnected if shareddatalayer is not connected to the backend data storage.
+         * @throw OperationInterrupted if shareddatalayer does not receive a reply from the backend data storage.
+         * @throw InvalidNamespace if given namespace does not meet the namespace format restrictions.
+         */
+        virtual Keys listKeys(const Namespace& ns,
+                              const std::string& pattern) = 0;
+
         /**
          * Remove all keys under the namespace. Found keys are removed atomically, i.e.
          * either all succeeds or all fails.