Update of code snippets in the docs (#1495)

Verified snippets to be sure they works as expected Relates-To: OLPEDGE-2865 Signed-off-by: Andrey Kashcheev <[email protected]>
heremaps · Apr 8, 2024 · 02352c7 · 02352c7
1 parent 91d6934
commit 02352c7
Show file tree

Hide file tree

Showing 5 changed files with 79 additions and 61 deletions.
diff --git a/docs/authenticate.md b/docs/authenticate.md
@@ -15,7 +15,7 @@ For instructions, see the [OAuth tokens](https://developer.here.com/documentatio
 
  You get the `credentials.properties` file.
 
-2. Initialize the authentification settings using the **here.access.key.іd** and **here.access.key.secret** from the `credentials.properties` file as `kKeyId` and `kKeySecret` respectively.
+2. Initialize the authentication settings using the **here.access.key.іd** and **here.access.key.secret** from the `credentials.properties` file as `kKeyId` and `kKeySecret` respectively.
 
  > #### Note
  > You can also retrieve your credentials from the `credentials.properties` file using the `ReadFromFile` method. For more information, see the [related API documentation](https://developer.here.com/documentation/sdk-cpp/api_reference/classolp_1_1authentication_1_1_authentication_credentials.html#a6bfd8347ebe89e45713b966e621dccdd).
@@ -56,25 +56,28 @@ You can use the `AuthenticationSettings` object to create the `OlpClientSettings
 3. Create an authentication client.
 
  ```cpp
- olp::authentication::AuthenticationSettings settings;
- settings.task_scheduler = task_scheduler;
- settings.network_request_handler = http_client;
- authentication::AutnhentucationClient client(settings);
+ olp::authentication::AuthenticationSettings auth_client_settings;
+ auth_client_settings.task_scheduler = task_scheduler;
+ auth_client_settings.network_request_handler = http_client;
+ olp::authentication::AuthenticationClient client(auth_client_settings);
  ```
 
 4. Create the `SignInProperties` object with your project ID.
 
  ```cpp
- authentication::SignInProperties signin_properties;
+ olp::authentication::AuthenticationClient::SignInProperties signin_properties;
  signin_properties.scope = "<project ID>";
  ```
 
-5. Create the `SignInClient` object.
+5. Call the `SignInClient` API on the previously created `client` object.
 
  ```cpp
- authentication:: SignInClient(AuthenticationCredentials credentials,
- SignInProperties properties,
- SignInClientCallback callback);
+ client.SignInClient(
+ credentials, signin_properties,
+ [](olp::authentication::Response<olp::authentication::SignInResult>
+ response) {
+  // Handle the response
+  });
  ```
 
 You get an access token.
@@ -98,13 +101,12 @@ You can use the `AuthenticationSettings` object to create the `OlpClientSettings
  olp::authentication::AuthenticationCredentials credentials(kKeyId, kKeySecret);
  ```
 
-3. Create an authentication client.
+3. Create an authentication client's settings.
 
  ```cpp
- olp::authentication::AuthenticationSettings settings;
- settings.task_scheduler = task_scheduler;
- settings.network_request_handler = http_client;
- authentication::AutnhentucationClient client(settings);
+ olp::authentication::AuthenticationSettings auth_client_settings;
+ auth_client_settings.task_scheduler = task_scheduler;
+ auth_client_settings.network_request_handler = http_client;
  ```
 
 4. Get your federated (Facebook or ArcGIS) properties.
@@ -114,36 +116,53 @@ You can use the `AuthenticationSettings` object to create the `OlpClientSettings
 5. Initialize your federated properties.
 
  ```cpp
- olp::authentication::AunthenticationClient::FederatedProperties properties;
+ olp::authentication::AuthenticationClient::FederatedProperties properties;
  properties.access_token = "your-access-token";
  ```
 
-6. Create the `SignInUserCallback` class.
-
- For more information, see the [`AuthenticationClient` reference documentation](https://developer.here.com/documentation/sdk-cpp/api_reference/classolp_1_1authentication_1_1_authentication_client.html).
-
-7. Create your own token provider using the authentication client created in step 3, your federated credentials, and the `SignInUserCallback` class.
+6. Create your own token provider using the authentication client's settings created in step 3, your federated credentials.
 
  > #### Note
  > You can call your custom token provider form different threads.
 
  ```cpp
- auto token = std::make_shared<std::string>();
-
- settings.token_provider = [token](){
- if (token->empty() || isExpired(token)) {
- std::promise<AuthenticationClient::SignInUserResponse> token_promise;
-
- auto callback = [&token_promise](AuthenticationClient::SignInUserResponse response)
- { token_promise.set(response); };
-
- authentication::AutnhentucationClient client(settings);
- client.SignInFacebook(credentials, properties, callback);
- auto response = token_promise.get_future().get();
- (*token) = response.GetResult().GetAccessToken();
- }
- return *token;
- }
+ auto token = std::make_shared<olp::client::OauthToken>();
+
+ olp::client::AuthenticationSettings auth_settings;
+ auth_settings.token_provider =
+ [token, auth_client_settings, credentials,
+ properties](olp::client::CancellationContext context)
+ -> olp::client::OauthTokenResponse {
+  if (context.IsCancelled()) {
+  return olp::client::ApiError::Cancelled();
+  }
+
+  if (!token->GetAccessToken().empty() &&
+ std::chrono::system_clock::to_time_t(
+ std::chrono::system_clock::now()) >= token->GetExpiryTime()) {
+ return *token;
+ }
+
+  std::promise<olp::authentication::AuthenticationClient::SignInUserResponse>
+  token_promise;
+
+  auto callback =
+  [&token_promise](
+  olp::authentication::AuthenticationClient::SignInUserResponse
+  response) { token_promise.set_value(std::move(response)); };
+
+  olp::authentication::AuthenticationClient client(auth_client_settings);
+  client.SignInFacebook(credentials, properties, callback);
+  auto response = token_promise.get_future().get();
+  if (!response) {
+  return response.GetError();
+  }
+
+  (*token) = olp::client::OauthToken(response.GetResult().GetAccessToken(),
+  response.GetResult().GetExpiresIn());
+
+  return *token;
+ };
  ```
 
 You get an access token. By default, it expires in 24 hours. To continue working with the HERE platform after your token expires, generate a new access token.

diff --git a/docs/create-platform-client-settings.md b/docs/create-platform-client-settings.md
@@ -38,7 +38,7 @@ You need to create the `OlpClientSettings` object to get catalog and partition m
  retry_settings.retry_condition = [](const olp::client::HttpResponse& response) {
   return olp::http::HttpStatusCode::TOO_MANY_REQUESTS == response.status;
  };
- retry_settings.backdown_strategy = ExponentialBackdownStrategy();
+ retry_settings.backdown_strategy = olp::client::ExponentialBackdownStrategy();
  retry_settings.max_attempts = 3;
  retry_settings.timeout = 60;
  retry_settings.initial_backdown_period = 200;
@@ -55,7 +55,7 @@ You need to create the `OlpClientSettings` object to get catalog and partition m
 
  ```cpp
  olp::cache::CacheSettings cache_settings;
- //On iOS, the path is relative to the Application Data folder.
+ // On iOS, the path is relative to the Application Data folder.
  cache_settings.disk_path_mutable = "path to mutable cache";
  cache_settings.disk_path_protected = "path to protected cache";
  cache_settings.max_disk_storage = 1024ull * 1024ull * 32ull;

diff --git a/docs/dataservice-cache-example.md b/docs/dataservice-cache-example.md
@@ -51,12 +51,14 @@ After building and running the example project, you see the following informatio
 
 ```bash
 [INFO] protected-cache-example - Mutable cache path is "none"
-[INFO] protected-cache-example - Protected cache path is "/tmp/cata.log_client_example/cache"
+[INFO] protected-cache-example - Protected cache path is "/tmp/catalog_client_example/cache"
 [INFO] ThreadPoolTaskScheduler - Starting thread 'OLPSDKPOOL_0'
-[INFO] CatalogRepository - cache catalog '@0^0' found!
-[INFO] PartitionsCacheRepository - Get 'hrn:here:data::olp-here-test:edge-example-catalog::versioned-world-layer::1::0::partition'
-[INFO] PartitionsRepository - cache data 'versioned-world-layer[1]@0^0' found!
-[INFO] DataRepository - cache data 'versioned-world-layer[1]@0^0' found!
+[DEBUG] CatalogCacheRepository - GetVersion -> 'hrn:here:data::olp-here-test:edge-example-catalog::latestVersion'
+[DEBUG] CatalogRepository - Latest cached version, hrn='hrn:here:data::olp-here-test:edge-example-catalog', version=0
+[DEBUG] PartitionsCacheRepository - Get 'hrn:here:data::olp-here-test:edge-example-catalog::versioned-world-layer::1::0::partition'
+[DEBUG] PartitionsRepository - GetPartitionById found in cache, hrn='hrn:here:data::olp-here-test:edge-example-catalog', key='versioned-world-layer[1]@0^2'
+[DEBUG] DataCacheRepository - Get 'hrn:here:data::olp-here-test:edge-example-catalog::versioned-world-layer::8daa637d-7c81-4322-a600-063f4ae0ef98::Data'
+[DEBUG] DataRepository - GetBlobData found in cache, hrn='hrn:here:data::olp-here-test:edge-example-catalog', key='8daa637d-7c81-4322-a600-063f4ae0ef98'
 [INFO] protected-cache-example - Request partition data - Success, data size - 3375
 ```
 
@@ -101,7 +103,7 @@ You can get data from a [versioned layer](https://developer.here.com/documentati
  auto request = olp::dataservice::read::DataRequest()
  .WithPartitionId(first_partition_id)
  .WithBillingTag(boost::none)
- .WithFetchOption(FetchOptions::OnlineIfNotFound);
+ .WithFetchOption(olp::dataservice::read::FetchOptions::OnlineIfNotFound);
  ```
 
 4. Call the `GetRequest` method with the `DataRequest` parameter.
@@ -113,8 +115,7 @@ You can get data from a [versioned layer](https://developer.here.com/documentati
 5. Wait for the `DataResponse` future.
 
  ```cpp
- olp::dataservice::read::DataResponse data_response =
- future.GetFuture().get();
+ olp::dataservice::read::DataResponse data_response = future.GetFuture().get();
  ```
 
 The `DataResponse` object holds details of the completed operation and is used to determine operation success and access resultant data:
@@ -136,5 +137,5 @@ if (data_response.IsSuccessful()) {
 The received data is stored in the cache. You can find the path to the cache in the log message.
 
  ```bash
- [INFO] protected-cache-example - Mutable cache path is "/tmp/cata.log_client_example/cache"
+ [INFO] protected-cache-example - Mutable cache path is "/tmp/catalog_client_example/cache"
  ```
diff --git a/docs/dataservice-read-catalog-example.md b/docs/dataservice-read-catalog-example.md
@@ -199,8 +199,7 @@ Catalog metadata contains a list of configurations that describe the catalog and
 3. Create the `CatalogRequest` object.
 
  ```cpp
- auto request =
- olp::dataservice::read::CatalogRequest();
+ auto request = olp::dataservice::read::CatalogRequest();
  ```
 
 4. (Optional) Set the needed parameters. For example, to set the billing tag, set the `WithBillingTag` parameter.
@@ -229,8 +228,7 @@ The `CatalogResponse` object holds details of the completed operation and is use
 
 ```cpp
 if (catalog_response.IsSuccessful()) {
- auto response_result =
-  catalog_response.GetResult();
+ const auto& response_result = catalog_response.GetResult();
  // Handle success
 } else {
  auto api_error = catalog_response.GetError();
@@ -300,9 +298,10 @@ Partition metadata consists of the following information about the partition:
 
  ```cpp
  auto request =
- olp::dataservice::read::PartitionsRequest()
- .WithBillingTag("MyBillingTag")
- .WithFetchOption(FetchOptions::OnlineIfNotFound);
+ olp::dataservice::read::PartitionsRequest()
+ .WithBillingTag("MyBillingTag")
+ .WithFetchOption(
+ olp::dataservice::read::FetchOptions::OnlineIfNotFound);
  ```
 
 4. Call `GetPartitions` method with the `PartitionRequest` parameter.
@@ -384,7 +383,7 @@ You can request any data version from a [versioned layer](https://developer.here
  auto request = olp::dataservice::read::DataRequest()
  .WithPartitionId(partition_id)
  .WithBillingTag("MyBillingTag")
- .WithFetchOption(FetchOptions::OnlineIfNotFound);
+ .WithFetchOption(olp::dataservice::read::FetchOptions::OnlineIfNotFound);
  ```
 
 4. Call the `GetRequest` method with the `DataRequest` parameter.
@@ -396,8 +395,7 @@ You can request any data version from a [versioned layer](https://developer.here
 5. Wait for the `DataResponse` future.
 
  ```cpp
- olp::dataservice::read::DataResponse data_response =
- future.GetFuture().get();
+ olp::dataservice::read::DataResponse data_response = future.GetFuture().get();
  ```
 
 The `DataResponse` object holds details of the completed operation and is used to determine operation success and access resultant data:
@@ -408,7 +406,7 @@ The `DataResponse` object holds details of the completed operation and is used t
 
 ```cpp
 if (data_response.IsSuccessful()) {
- auto response_result = data_response.GetResult();
+ const auto& response_result = data_response.GetResult();
  // Handle success
 } else {
  auto api_error = data_response.GetError();

diff --git a/examples/ProtectedCacheExample.cpp b/examples/ProtectedCacheExample.cpp
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2020-2021 HERE Europe B.V.
+ * Copyright (C) 2020-2024 HERE Europe B.V.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -36,7 +36,7 @@ constexpr auto kLogTag = "protected-cache-example";
 #ifdef _WIN32
 constexpr auto kClientCacheDir = "\\catalog_client_example\\cache";
 #else
-constexpr auto kClientCacheDir = "/cata.log_client_example/cache";
+constexpr auto kClientCacheDir = "/catalog_client_example/cache";
 #endif
 
 std::string first_layer_id("versioned-world-layer");