Update VersionedLayerClient example and doxygen. (#693)

VersionedLayerClient API is changed, version is specified in constructor
instead of DataRequest now. So the goal of this change is to adapt
example and doxygen to the new API. Added new argument for catalog
version.

Resolves: OLPEDGE-1566

Signed-off-by: Kostiantyn Zvieriev <[email protected]>

Author: kzvieriev

examples/Options.h

@@ -36,6 +36,11 @@ const Option kKeySecretOption{"-s", "--key_secret",
 const Option kCatalogOption{"-c", "--catalog",
                             "Catalog HRN (HERE Resource Name)."};
 
+const Option kCatalogVersionOption{
+    "-v", "--catalog_version",
+    "The version of the catalog from which you wan to "
+    "get data(used in read example, optional)."};
+
 const Option kLayerIdOption{"-l", "--layer_id",
                             "The layer ID inside the catalog where you want to "
                             "publish data to(required for write example)."};

examples/ReadExample.cpp

@@ -118,7 +118,8 @@ bool HandleDataResponse(
 }
 }  // namespace
 
-int RunExampleRead(const AccessKey& access_key, const std::string& catalog) {
+int RunExampleRead(const AccessKey& access_key, const std::string& catalog,
+                   const boost::optional<int64_t>& catalog_version) {
   // Create a task scheduler instance
   std::shared_ptr<olp::thread::TaskScheduler> task_scheduler =
       olp::client::OlpClientSettingsFactory::CreateDefaultTaskScheduler(1u);
@@ -174,9 +175,10 @@ int RunExampleRead(const AccessKey& access_key, const std::string& catalog) {
     first_layer_id = HandleCatalogResponse(catalog_response);
   }
 
-  // Create appropriate layer client with HRN, layer name and settings.
+  // Create appropriate layer client with HRN, layer name, version and settings.
   olp::dataservice::read::VersionedLayerClient layer_client(
-      olp::client::HRN(catalog), first_layer_id, client_settings);
+      olp::client::HRN(catalog), first_layer_id, catalog_version,
+      client_settings);
 
   std::string first_partition_id;
   if (!first_layer_id.empty()) {

examples/ReadExample.h

@@ -21,12 +21,18 @@
 
 #include "Examples.h"
 
+#include <boost/optional.hpp>
+
 /**
  * @brief Dataservice read example. Authenticate client using access key id and
  * secret. Get catalog and partition metadata, as well as partition data using
  * the HERE Open Location Platform.
  * @param access_key here.access.key.id and here.access.key.secret.
- * @param The HERE Resource Name (HRN) of the catalog from which you want to read data.
+ * @param catalog The HERE Resource Name (HRN) of the catalog from which you
+ * want to read data.
+ * @param catalog_version The desired version of the catalog.
  * @return result of publish data(0 - if succeed)
  */
-int RunExampleRead(const AccessKey& access_key, const std::string& catalog);
+int RunExampleRead(
+    const AccessKey& access_key, const std::string& catalog,
+    const boost::optional<int64_t>& catalog_version = boost::none);

examples/main.cpp

@@ -22,9 +22,10 @@
 #include "ReadExample.h"
 #include "WriteExample.h"
 
-#include <iostream>
 #include <stdio.h>
 #include <string.h>
+#include <iostream>
+#include <sstream>
 
 bool IsMatch(const std::string& name, const tools::Option& option) {
   return name == option.short_name || name == option.long_name;
@@ -42,6 +43,8 @@ constexpr auto usage =
     "example [read, write, cache] \n -i [--key_id] here.access.key.id \n -s "
     "[--key_secret] here.access.key.secret \n"
     " -c [--catalog] catalog HRN (HERE Resource Name). \n"
+    " -v [--catalog_version] The version of the catalog from which you wan to"
+    "get data(used in read example, optional). \n"
     " -l [--layer_id] the layer ID inside the catalog where you want to "
     "publish data to(required for write example). \n"
     " -h [--help]: show usage \n For "
@@ -57,7 +60,9 @@ int RequiredArgumentError(const tools::Option& arg) {
   return 0;
 }
 int ParseArguments(const int argc, char** argv, AccessKey& access_key,
-                   std::string& catalog, std::string& layer_id) {
+                   std::string& catalog,
+                   boost::optional<int64_t>& catalog_version,
+                   std::string& layer_id) {
   int examples_to_run = 0;
 
   const std::vector<std::string> arguments(argv + 1, argv + argc);
@@ -104,6 +109,16 @@ int ParseArguments(const int argc, char** argv, AccessKey& access_key,
         return RequiredArgumentError(tools::kCatalogOption);
       }
       catalog = *it;
+    } else if (IsMatch(*it, tools::kCatalogVersionOption)) {
+      ++it;
+      catalog_version = 0;
+      std::stringstream ss(*it);
+      ss >> *catalog_version;
+      if (ss.fail() || !ss.eof()) {
+        std::cout << "invalid catalog version value -- '" << *it
+                  << "', but int64 is expected." << std::endl;
+        catalog_version = boost::none;
+      }
     } else if (IsMatch(*it, tools::kLayerIdOption)) {
       if (++it == arguments.end()) {
         return RequiredArgumentError(tools::kLayerIdOption);
@@ -126,10 +141,12 @@ int ParseArguments(const int argc, char** argv, AccessKey& access_key,
 }
 
 int RunExamples(const AccessKey& access_key, int examples_to_run,
-                const std::string& catalog, const std::string& layer_id) {
+                const std::string& catalog,
+                const boost::optional<int64_t>& catalog_version,
+                const std::string& layer_id) {
   if (examples_to_run & Examples::read_example) {
     std::cout << "Read Example" << std::endl;
-    if (RunExampleRead(access_key, catalog)) {
+    if (RunExampleRead(access_key, catalog, catalog_version)) {
       std::cout << "Read Example failed" << std::endl;
       return -1;
     }
@@ -159,9 +176,10 @@ int main(int argc, char** argv) {
   std::string catalog;     // the HRN of the catalog to which you to publish data
   std::string layer_id;    // the of the layer inside the catalog to which you
                            // want to publish data
+  boost::optional<int64_t> catalog_version;  // version of the catalog.
 
-  int examples_to_run =
-      ParseArguments(argc, argv, access_key, catalog, layer_id);
+  int examples_to_run = ParseArguments(argc, argv, access_key, catalog,
+                                       catalog_version, layer_id);
   if (examples_to_run == 0) {
     return 0;
   }
@@ -183,5 +201,6 @@ int main(int argc, char** argv) {
               << std::endl;
   }
 
-  return RunExamples(access_key, examples_to_run, catalog, layer_id);
+  return RunExamples(access_key, examples_to_run, catalog, catalog_version,
+                     layer_id);
 }

olp-cpp-sdk-dataservice-read/include/olp/dataservice/read/VersionedLayerClient.h

@@ -76,9 +76,9 @@ class VersionedLayerClientImpl;
  * client_settings.task_scheduler = std::move(task_scheduler);
  * client_settings.network_request_handler = std::move(http_client);
  *
- * VersionedLayerClient client{"hrn:here:data:::your-catalog-hrn", "your-layer-id", client_settings};
+ * VersionedLayerClient client{"hrn:here:data:::your-catalog-hrn", "your-layer-id", "catalog-version", client_settings};
  * auto callback = [](olp::client::ApiResponse<olp::model::Data, olp::client::ApiError> response) {};
- * auto request = DataRequest().WithVersion(100).WithPartitionId("269");
+ * auto request = DataRequest().WithPartitionId("269");
  * auto token = client.GetData(request, callback);
  * @endcode
  *