From b8ba02279831e2f58fa31abceedba38712949720 Mon Sep 17 00:00:00 2001 From: Andrey Kashcheev Date: Thu, 18 Jun 2026 17:20:07 +0200 Subject: [PATCH] Documentation update - Migrated dev guide to have it here on GitHub - Updated existing docs to point to the new guide - Updated links to HERE docs portal Relates-To: DATASDK-92, DATASDK-99 Signed-off-by: Andrey Kashcheev --- README.md | 8 +- docs/OverallArchitecture.md | 4 +- docs/authenticate.md | 16 ++-- docs/create-platform-client-settings.md | 2 +- docs/dataservice-cache-example.md | 6 +- docs/dataservice-read-catalog-example.md | 6 +- ...aservice-read-from-stream-layer-example.md | 4 +- docs/dataservice-write-example.md | 8 +- docs/dev_guide/README.md | 40 +++++++++ docs/dev_guide/SUMMARY.md | 22 +++++ docs/dev_guide/topics/get-catalog-metadata.md | 86 ++++++++++++++++++ .../topics/get-data-from-stream-layer.md | 56 ++++++++++++ .../topics/get-data-from-volatile-layer.md | 59 +++++++++++++ docs/dev_guide/topics/get-data.md | 9 ++ .../topics/get-partition-metadata.md | 87 +++++++++++++++++++ .../topics/manage-eviction-protection.md | 45 ++++++++++ .../topics/publish-data-to-index-layer.md | 64 ++++++++++++++ .../topics/publish-data-to-versioned-layer.md | 83 ++++++++++++++++++ .../topics/publish-data-to-volatile-layer.md | 50 +++++++++++ docs/dev_guide/topics/publish-data.md | 8 ++ docs/dev_guide/topics/run-examples.md | 7 ++ .../technical-details-and-prerequisites.md | 5 ++ docs/dev_guide/topics/use-cases.md | 19 ++++ docs/dev_guide/topics/work-with-cache.md | 28 ++++++ docs/get-started.md | 12 +-- docs/work-with-data-apis.md | 2 +- 26 files changed, 702 insertions(+), 34 deletions(-) create mode 100644 docs/dev_guide/README.md create mode 100644 docs/dev_guide/SUMMARY.md create mode 100644 docs/dev_guide/topics/get-catalog-metadata.md create mode 100644 docs/dev_guide/topics/get-data-from-stream-layer.md create mode 100644 docs/dev_guide/topics/get-data-from-volatile-layer.md create mode 100644 docs/dev_guide/topics/get-data.md create mode 100644 docs/dev_guide/topics/get-partition-metadata.md create mode 100644 docs/dev_guide/topics/manage-eviction-protection.md create mode 100644 docs/dev_guide/topics/publish-data-to-index-layer.md create mode 100644 docs/dev_guide/topics/publish-data-to-versioned-layer.md create mode 100644 docs/dev_guide/topics/publish-data-to-volatile-layer.md create mode 100644 docs/dev_guide/topics/publish-data.md create mode 100644 docs/dev_guide/topics/run-examples.md create mode 100644 docs/dev_guide/topics/technical-details-and-prerequisites.md create mode 100644 docs/dev_guide/topics/use-cases.md create mode 100644 docs/dev_guide/topics/work-with-cache.md diff --git a/README.md b/README.md index 719ab6ec1..3445ddb8b 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ HERE Data SDK for C++ is a C++ client for the Getting Started Guide and Developer Guide. +To learn how to install and use the Data SDK, see the Getting Started Guide and Developer Guide. ## Health check @@ -30,13 +30,13 @@ To learn how to install and use the Data SDK, see the Developer Guide and API Reference. +For more information on Data API, see its Developer Guide and API Reference. When new API is introduced in Data SDK for C++, the old one is not deleted straight away. The standard API deprecation time is 6 months. It gives you time to switch to new code. However, we do not provide ABI backward compatibility. -Learn more about deprecated methods, functions, and parameters in the Data SDK for C++ API Reference and changelog. +Learn more about deprecated methods, functions, and parameters in the Data SDK for C++ API Reference and changelog. -For more information on Data SDK for C++, see our Developer Guide. +For more information on Data SDK for C++, see our Developer Guide. ## Supported platforms diff --git a/docs/OverallArchitecture.md b/docs/OverallArchitecture.md index b87b01826..49fc434f1 100644 --- a/docs/OverallArchitecture.md +++ b/docs/OverallArchitecture.md @@ -2,7 +2,7 @@ ## Outline -This document describes the overall architecture of HERE Data SDK for C++ (here also referred to as SDK). For an overview of the scope and the features of the SDK, see [README.md](../README.md#why-use). +This document describes the overall architecture of HERE Data SDK for C++ (here also referred to as SDK). For an overview of the scope and the features of the SDK, see [README.md](../README.md#use-the-sdk). ## Component overview @@ -56,7 +56,7 @@ The dataservice-read module wraps a subset of the Data REST API related to readi * [Config API](https://www.here.com/docs/bundle/data-api-config-v1-api-reference/page/index.html) * [Metadata API](https://www.here.com/docs/bundle/data-api-metadata-v1-api-reference/page/index.html) * [Query API](https://www.here.com/docs/bundle/data-api-query-v1-api-reference/page/index.html) - * [Volatile API](https://www.here.com/docs/bundle/data-api-volatile-blob-v1-api-reference/page/index.html) + * [Volatile API](https://docs.here.com/data-api/reference/getvolatileblob) * Index layer (not supported yet). Used Data APIs: * [Index API](https://www.here.com/docs/bundle/data-api-index-v1-api-reference/page/index.html) * [Blob API](https://www.here.com/docs/bundle/data-api-blob-v1-api-reference/page/index.html) diff --git a/docs/authenticate.md b/docs/authenticate.md index 12e1859f5..9d021a855 100644 --- a/docs/authenticate.md +++ b/docs/authenticate.md @@ -2,7 +2,7 @@ To authenticate to the HERE platform and start working with HERE Data SDK for C++, you need to get an access token. You can receive it using a [default token provider](#authenticate-using-a-default-token-provider), [project authentication](#authenticate-using-project-authentication), or [federated credentials](#authenticate-using-federated-credentials). -For instructions, see the [OAuth tokens](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/dev-token.html) section in the Identity & Access Management Developer Guide. +For instructions, see the [OAuth tokens](https://docs.here.com/identity-and-access-management/docs/manage-api-oauth) section in the Identity & Access Management Developer Guide. > #### Note > Keep your credentials secure and do not disclose them. Make sure that your credentials are not stored in a way that enables others to access them. @@ -11,14 +11,14 @@ For instructions, see the [OAuth tokens](https://www.here.com/docs/bundle/identi 1. Get your platform credentials. - For instructions, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. + For instructions, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. You get the `credentials.properties` file. 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://www.here.com/docs/bundle/data-sdk-for-cpp-api-reference/page/namespaceolp_1_1authentication.html#). + > You can also retrieve your credentials from the `credentials.properties` file using the `ReadFromFile` method. For more information, see the [related API documentation](https://heremaps.github.io/here-data-sdk-cpp/namespaceolp_1_1authentication.html). ```cpp olp::authentication::Settings settings({kKeyId, kKeySecret}); @@ -42,12 +42,12 @@ You can use the `AuthenticationSettings` object to create the `OlpClientSettings 1. Get your platform credentials. - For instructions, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. + For instructions, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. 2. Initialize the `AuthenticationCredentials` class 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://www.here.com/docs/bundle/data-sdk-for-cpp-api-reference/page/namespaceolp_1_1authentication.html#). + > You can also retrieve your credentials from the `credentials.properties` file using the `ReadFromFile` method. For more information, see the [related API documentation](https://heremaps.github.io/here-data-sdk-cpp/namespaceolp_1_1authentication.html). ```cpp olp::authentication::AuthenticationCredentials credentials(kKeyId, kKeySecret); @@ -88,14 +88,14 @@ You can use the `AuthenticationSettings` object to create the `OlpClientSettings 1. Get your platform credentials. - For instructions, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. + For instructions, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. You get the `credentials.properties` file. 2. Initialize the `AuthenticationCredentials` class 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://www.here.com/docs/bundle/data-sdk-for-cpp-api-reference/page/namespaceolp_1_1authentication.html#). + > You can also retrieve your credentials from the `credentials.properties` file using the `ReadFromFile` method. For more information, see the [related API documentation](https://heremaps.github.io/here-data-sdk-cpp/namespaceolp_1_1authentication.html). ```cpp olp::authentication::AuthenticationCredentials credentials(kKeyId, kKeySecret); @@ -111,7 +111,7 @@ You can use the `AuthenticationSettings` object to create the `OlpClientSettings 4. Get your federated (Facebook or ArcGIS) properties. - You should have at least your federated access token. For the complete list of federated properties, see the [related documentation](https://www.here.com/docs/bundle/data-sdk-for-cpp-api-reference/page/structolp_1_1authentication_1_1AuthenticationClient_1_1FederatedProperties.html). + You should have at least your federated access token. For the complete list of federated properties, see the [related documentation](https://heremaps.github.io/here-data-sdk-cpp/structolp_1_1authentication_1_1AuthenticationClient_1_1FederatedProperties.html). 5. Initialize your federated properties. diff --git a/docs/create-platform-client-settings.md b/docs/create-platform-client-settings.md index e6ed435c1..cde11cf3f 100644 --- a/docs/create-platform-client-settings.md +++ b/docs/create-platform-client-settings.md @@ -67,7 +67,7 @@ You need to create the `OlpClientSettings` object to get catalog and partition m olp::client::OlpClientSettingsFactory::CreateDefaultCache(cache_settings); ``` - To learn how to get or change cache size, see [Work with a cache](https://www.here.com/docs/bundle/data-sdk-for-cpp-developer-guide/page/topics/work-with-cache.html). + To learn how to get or change cache size, see [Work with a cache](./dev_guide/topics/work-with-cache.md). 6. Set up the `OlpClientSettings` object, and if you want to add the expiration limit for the data that is stored in the cache, set the `default_cache_expiration` to the needed expiration time. diff --git a/docs/dataservice-cache-example.md b/docs/dataservice-cache-example.md index b355c14f5..ac3166d6b 100644 --- a/docs/dataservice-cache-example.md +++ b/docs/dataservice-cache-example.md @@ -6,7 +6,7 @@ On this page, find instructions on how to build and run the cache example projec 1. On the [Apps & keys](https://platform.here.com/admin/apps) page, copy your application access key ID and access key secret. - For instructions on how to get the access key ID and access key secret, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. + For instructions on how to get the access key ID and access key secret, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. 2. In `examples/main.cpp`, replace the placeholders with your access key ID, access key secret, and Here Resource Name (HRN) of the catalog. @@ -64,9 +64,9 @@ After building and running the example project, you see the following informatio ## How it works -### Get data from a versioned layer with a cache +### Get data from a versioned layer with a cache -You can get data from a [versioned layer](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/layers.html#versioned-layers) with a mutable or protected cache. +You can get data from a [versioned layer](https://docs.here.com/data-api/docs/layers#versioned-layers) with a mutable or protected cache. **To get data from the versioned layer with mutable cache:** diff --git a/docs/dataservice-read-catalog-example.md b/docs/dataservice-read-catalog-example.md index 127bece5a..a728796de 100644 --- a/docs/dataservice-read-catalog-example.md +++ b/docs/dataservice-read-catalog-example.md @@ -6,7 +6,7 @@ On this page, find instructions on how to build and run the read example project 1. On the [Apps & keys](https://platform.here.com/admin/apps) page, copy your application access key ID and access key secret. - For instructions on how to get the access key ID and access key secret, see [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. + For instructions on how to get the access key ID and access key secret, see [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. 2. In `examples/main.cpp`, replace the placeholders with your access key ID, access key secret, and Here Resource Name (HRN) of the catalog. @@ -74,7 +74,7 @@ To integrate the Data SDK libraries in the Android example project: 2. In `examples/android/app/src/main/cpp/MainActivityNative.cpp.in`, replace the placeholders with your application access key ID, access key secret, and catalog HRN and specify that the example should run `RunExampleRead`. > #### Note -> To learn how to get the access key ID and access key secret, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. +> To learn how to get the access key ID and access key secret, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. ### Build the Data SDK on Android @@ -124,7 +124,7 @@ To integrate the Data SDK libraries in the iOS example project written in the Ob 3. In `examples/ios/ViewController.mm`, replace the placeholders with your application access key ID, access key secret, and catalog HRN and specify that the example should run `RunExampleRead`. > #### Note -> To learn how to get the access key ID and access key secret, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. +> To learn how to get the access key ID and access key secret, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. ### Build the Data SDK on iOS diff --git a/docs/dataservice-read-from-stream-layer-example.md b/docs/dataservice-read-from-stream-layer-example.md index f57927090..21e9739b3 100644 --- a/docs/dataservice-read-from-stream-layer-example.md +++ b/docs/dataservice-read-from-stream-layer-example.md @@ -6,7 +6,7 @@ On this page, you can find instructions on how to build and run the cache exampl 1. On the [Apps & keys](https://platform.here.com/admin/apps) page, copy your application access key ID and access key secret. - For instructions on how to get the access key ID and access key secret, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. + For instructions on how to get the access key ID and access key secret, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. 2. In examples/main.cpp, replace the placeholders with your access key ID, access key secret, and Here Resource Name (HRN) of the catalog. @@ -62,7 +62,7 @@ After building and running the example project, you see the following informatio ### Get data from a stream layer -You can read messages from a [stream layer](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/layers.html#stream-layers) if you subscribe to it. +You can read messages from a [stream layer](https://docs.here.com/data-api/docs/creating-stream-layer) if you subscribe to it. **To get data from the stream layer:** diff --git a/docs/dataservice-write-example.md b/docs/dataservice-write-example.md index 355663473..78084e8ae 100644 --- a/docs/dataservice-write-example.md +++ b/docs/dataservice-write-example.md @@ -6,7 +6,7 @@ On this page, find instructions on how to build and run the write example projec 1. On the [Apps & keys](https://platform.here.com/admin/apps) page, copy your application access key ID and access key secret. - For instructions on how to get the access key ID and access key secret, see [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. + For instructions on how to get the access key ID and access key secret, see [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. 2. In examples/main.cpp, replace the placeholders with your access key ID, access key secret, Here Resource Name (HRN) of the catalog, and name of the layer to which you want to publish data. @@ -64,7 +64,7 @@ To integrate the Data SDK libraries in the Android example project: 2. In `examples/android/app/src/main/cpp/MainActivityNative.cpp.in`, replace the placeholders with your application access key ID, access key secret, catalog HRN, and layer name and specify that the example should run `RunExampleWrite`. > #### Note -> To learn how to get the access key ID and access key secret, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. +> To learn how to get the access key ID and access key secret, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. ### Build the Data SDK on Android @@ -114,7 +114,7 @@ To integrate the Data SDK libraries in the iOS example application written in th 3. In `examples/ios/ViewController.mm`, replace the placeholders with your application access key ID, access key secret, catalog HRN, and layer name and specify that the example should run `RunExampleWrite`. > #### Note -> To learn how to get the access key ID and access key secret, see the [Register your application](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/topics/plat-token.html#step-1-register-your-application-and-get-credentials) section in the Identity & Access Management Developer Guide. +> To learn how to get the access key ID and access key secret, see the [Register your application](https://docs.here.com/identity-and-access-management/docs/plat-using-oidc#step-2---register-your-app-and-get-credentials) section in the Identity & Access Management Developer Guide. > ```bash mkdir build && cd build @@ -159,7 +159,7 @@ If you encounter an error message, for a detailed error description, check the d ### Publish data to a stream layer -You can create a queue that streams data to data consumers in real time using a [stream layer](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/layers.html#stream-layers). +You can create a queue that streams data to data consumers in real time using a [stream layer](https://docs.here.com/data-api/docs/creating-stream-layer). **To publish data to the stream layer:** diff --git a/docs/dev_guide/README.md b/docs/dev_guide/README.md new file mode 100644 index 000000000..0b6f0fd19 --- /dev/null +++ b/docs/dev_guide/README.md @@ -0,0 +1,40 @@ +# Introduction + +HERE Data SDK for C++ provides an interface to access the HERE platform. It is a modern (C++11), lightweight, and modular SDK with minimal dependencies targeted towards a wide range of hardware platforms from embedded devices to desktops. + +The Data SDK for C++ package contains three independent modules that focus on different activities: + +- `olp-cpp-sdk-authentication` – gets OAuth2 bearer tokens used to confirm platform requests. +- `olp-cpp-sdk-dataservice-read` – downloads and caches data from the platform. +- `olp-cpp-sdk-dataservice-write` – queues and uploads data to the platform layers. + +For more information about the modules, see the [architectural overview](https://github.com/heremaps/here-olp-sdk-cpp/blob/master/docs/OverallArchitecture.md). + +HERE is committed to respecting your privacy and to complying with applicable data protection and privacy laws. For more information, see the [HERE Privacy Charter](https://www.here.com/en-gb/here-privacy-charter). + +For more information on HERE data security and durability best practices, see the [Data API](https://docs.here.com/data-api/docs/data-security). + +## Why use + +HERE Data SDK for C++ provides support for the core HERE platform use cases through a set of native C++ interfaces. The SDK is intended to save you time and effort on using HERE REST APIs. It provides a set of stable APIs that simplify complex platform operations and keeps up to date with the latest HERE REST API changes. + +The Data SDK for C++ is a modern (C++11), lightweight, and modular SDK with minimal dependencies targeted towards a wide range of hardware platforms from embedded devices to desktops. + +This SDK lets you: + +- Authenticate to HERE platform. +- Read catalog and partition metadata. +- Retrieve data from versioned, volatile, and stream layers of the platform catalogs. +- Upload data to the platform. + +Additionally, the SDK includes classes for work with geospatial tiling schemes that are used by most platform catalog layers. + +## Backward Compatibility + +We try to develop and maintain our API in a way that preserves its compatibility with the existing applications. Changes in the Data SDK for C++ are greatly influenced by the Data API development. Data API introduces breaking changes 6 months in advance. Therefore, you may need to migrate to a new version of the Data SDK for C++ every half a year. + +For more information on Data API, see its [Developer Guide](https://docs.here.com/data-api/docs/data-api-intro) and [API Reference](https://docs.here.com/data-api/reference). + +When new API is introduced in the Data SDK for C++, the old one is not deleted straight away. The standard API deprecation time is six months. It gives you time to switch to new code. However, we do not provide ABI backward compatibility. + +All of the deprecated methods, functions, and parameters are documented in the Data SDK for C++ [API Reference](https://heremaps.github.io/here-data-sdk-cpp/index.html) and [changelog](https://github.com/heremaps/here-olp-sdk-cpp/blob/master/CHANGELOG.md). \ No newline at end of file diff --git a/docs/dev_guide/SUMMARY.md b/docs/dev_guide/SUMMARY.md new file mode 100644 index 000000000..87f430b6d --- /dev/null +++ b/docs/dev_guide/SUMMARY.md @@ -0,0 +1,22 @@ +# Data SDK for C++ Developer Guide + +- [Introduction](README.md) +- [Get started](../get-started.md) + - [Create platform client settings](../create-platform-client-settings.md) + - [Work with a cache](topics/work-with-cache.md) +- [Use cases](topics/use-cases.md) + - [Authenticate to the HERE platform](../authenticate.md) + - [Manage eviction protection](topics/manage-eviction-protection.md) + - [Get catalog metadata](topics/get-catalog-metadata.md) + - [Get partition metadata](topics/get-partition-metadata.md) + - [Get data](topics/get-data.md) + - [Get data from a versioned layer](../dataservice-read-catalog-example.md#get-data-from-a-versioned-layer) + - [Get data from a versioned layer with a cache](../dataservice-cache-example.md#get-data-from-a-versioned-layer-with-a-cache) + - [Get data from a volatile layer](topics/get-data-from-volatile-layer.md) + - [Get data from a stream layer](../dataservice-read-from-stream-layer-example.md#get-data-from-a-stream-layer) + - [Publish data](topics/publish-data.md) + - [Publish data to a versioned layer](topics/publish-data-to-versioned-layer.md) + - [Publish data to a volatile layer](topics/publish-data-to-volatile-layer.md) + - [Publish data to a stream layer](../dataservice-write-example.md#publish-data-to-a-stream-layer) + - [Publish data to an index layer](topics/publish-data-to-index-layer.md) + - [Work with unsupported REST Data APIs](../work-with-data-apis.md) diff --git a/docs/dev_guide/topics/get-catalog-metadata.md b/docs/dev_guide/topics/get-catalog-metadata.md new file mode 100644 index 000000000..63f79a4f1 --- /dev/null +++ b/docs/dev_guide/topics/get-catalog-metadata.md @@ -0,0 +1,86 @@ +# Get catalog metadata + +Catalog metadata contains a list of configurations that describe the catalog and its layers. Configuration information about the catalog includes the following metadata: + +- Name +- HERE Resource Name (HRN) +- Description +- Owner +- Version +- Layer information + +**To get catalog metadata:** + +1. Create the `OlpClientSettings` object. + + For instructions, see [Create platform client settings](../../create-platform-client-settings.md). + +2. Create the `CatalogClient` object with the catalog HRN and platform client settings from step 1. + + ```cpp + olp::dataservice::read::CatalogClient catalog_client( + olp::client::HRN(kCatalogHRN), client_settings); + ``` + +3. Create the `CatalogRequest` object. + + ```cpp + auto request = olp::dataservice::read::CatalogRequest(); + ``` + +4. (Optional) Set the needed parameters. For example, to set the billing tag, set the `WithBillingTag` parameter. + + ```cpp + request.WithBillingTag("MyBillingTag"); + ``` + +5. Call the `GetRequest` method with the `CatalogRequest` parameter. + + ```cpp + auto future = catalog_client.GetCatalog(request); + ``` + +6. Wait for `CatalogResponse` future. + + ```cpp + olp::dataservice::read::CatalogResponse catalog_response = future.GetFuture().get(); + ```` + +The `CatalogResponse` object holds details of the completed operation and is used to determine operation success and access resultant data: + +- `IsSuccessful()` – if the operation is successful, returns `true`. Otherwise, returns `false`. +- `GetResult()` – if the operation is successful, returns the following resultant data: `olp::dataservice::read::CatalogResult` +- `GetError()` – contains error information as a result of an error in the `olp::client::ApiError` object. + +```cpp +if (catalog_response.IsSuccessful()) { + const auto& response_result = catalog_response.GetResult(); + // Handle success +} else { + auto api_error = catalog_response.GetError(); + // Handle fail +} +``` + +The `CatalogResult` class contains the following methods used to get details of the relevant catalog: + +- `GetId` – returns the catalog ID. +- `GetHrn` – returns the catalog `HRN`. +- `GetName` – returns the catalog name. +- `GetSummary` – returns the summary description of the catalog. +- `GetDescription` – returns the full description of the catalog. +- `GetCoverage` – returns the coverage area of the catalog. +- `GetOwner` – returns the identity of the catalog owner. +- `GetTags` – returns the catalog tags collection. +- `GetBillingTags` – returns the billing tags set on the catalog. +- `GetCreated` – returns the catalog creation time. +- `GetLayers` – returns details of the layers contained in the catalog. +- `GetVersion` – returns the current catalog version number. +- `GetNotifications` – returns the catalog notification status. + +The `ApiError` class contains the following methods used to get details of the incurred error: + +- `GetErrorCode` – returns the `ErrorCode` value defined by the `olp::client::ErrorCode enum`. For more details, see `ErrorCode.h`. +- `GetHttpStatusCode` – returns the HTTP response code. +- `GetMessage` – returns a text description of the encountered error. +- `ShouldRetry` – returns `true` if this operation can be retried. \ No newline at end of file diff --git a/docs/dev_guide/topics/get-data-from-stream-layer.md b/docs/dev_guide/topics/get-data-from-stream-layer.md new file mode 100644 index 000000000..3963f285a --- /dev/null +++ b/docs/dev_guide/topics/get-data-from-stream-layer.md @@ -0,0 +1,56 @@ +# Get data from a stream layer + +You can read messages from a [stream layer](https://docs.here.com/data-api/docs/layers#stream-layers) if you subscribe to it. + +**To get data from the stream layer:** + +1. Create the `OlpClientSettings` object. + + For instructions, see [Create platform client settings](../../create-platform-client-settings.md). + +2. Create the `StreamLayerClient` object with the HERE Resource Name (HRN) of the catalog that contains the layer, layer ID, and platform client settings from step 1. + + ```cpp + olp::dataservice::read::StreamLayerClient client( + client::HRN catalog, std::string layer_id, + client::OlpClientSettings settings); + ``` + +3. Create the `SubscribeRequest` object with the `serial` or `parallel` subscription type. + + - If your application should read smaller volumes of data using a single subscription, use the `serial` subscription type. + + - If your application should read large volumes of data in a parallel manner, use the `parallel` subscription type and subscription ID. + + ```cpp + auto request = olp::dataservice::read::SubscribeRequest() + .WithSubscriptionMode(olp::dataservice::read::SubscribeRequest::SubscriptionMode::kSerial)); + ``` + +4. Call the `Subscribe` method with the `SubscribeRequest` parameter. + + ```cpp + client::CancellableFuture Subscribe( + SubscribeRequest request); + ``` + + You receive a subscription ID from the requested subscription to the selected layer. + +5. Call the `Poll` method. + + ```cpp + client::CancellableFuture Poll(); + ``` + + You get messages with the layer data and partition metadata. The `Poll` method also commits the offsets, so you can continue polling new messages. + + If the data size is less than 1 MB, the data field is populated. If the data size is greater than 1 MB, you get a data handle that points to the object stored in the blob store. + +6. If the data size is greater than 1 MB, call the `GetData` method with the `Messages` instance. + + ```cpp + client::CancellableFuture GetData( + const model::Message& message); + ``` + +You get data from the requested partition. diff --git a/docs/dev_guide/topics/get-data-from-volatile-layer.md b/docs/dev_guide/topics/get-data-from-volatile-layer.md new file mode 100644 index 000000000..2ca1343f9 --- /dev/null +++ b/docs/dev_guide/topics/get-data-from-volatile-layer.md @@ -0,0 +1,59 @@ +# Get data from a volatile layer + +You can only get the latest published data from a [volatile layer](https://docs.here.com/data-api/docs/layers#volatile-layers). + +**To get data from the volatile layer:** + +1. Create the `OlpClientSettings` object. + + For instructions, see [Create platform client settings](../../create-platform-client-settings.md). + +2. Create the `VolatileLayerClient` object with the HERE Resource Name (HRN) of the catalog that contains the layer, the layer ID, and the platform client settings from step 1. + + ```cpp + olp::dataservice::read::VolatileLayerClient layer_client( + olp::client::HRN(kCatalogHRN), layer_id, client_settings); + ``` + +3. Create the `DataRequest` object with the partition ID and one of the following fetch options: + + - (Default) To query network if the requested resource is not found in the cache, use `OnlineIfNotFound`. + - To skip cache lookups and query the network right away, use `OnlineOnly`. + - To return immediately if a cache lookup fails, use `CacheOnly`. + - To return the requested cached resource if it is found and update the cache in the background, use `CacheWithUpdate`. + + ```cpp + auto request = olp::dataservice::read::DataRequest() + .WithPartitionId(partition_id) + .WithBillingTag("MyBillingTag") + .WithFetchOption(FetchOptions::OnlineIfNotFound); + ``` + +4. Call the `GetRequest` method with the `DataRequest` parameter. + + ```cpp + auto future = layer_client.GetData(request); + ``` + +5. Wait for the `DataResponse` future. + + ```cpp + 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: + +- `IsSuccessful()` – if the operation is successful, returns `true`. Otherwise, returns `false`. +- `GetResult()`– if the operation is successful, returns the following resultant data: `olp::dataservice::read::DataResult` +- `GetError()` – contains error information as a result of an error in the `olp::client::ApiError` object. + +```cpp +if (data_response.IsSuccessful()) { + auto response_result = data_response.GetResult(); + // Handle success +} else { + auto api_error = data_response.GetError(); + // Handle fail +} +``` diff --git a/docs/dev_guide/topics/get-data.md b/docs/dev_guide/topics/get-data.md new file mode 100644 index 000000000..86618e987 --- /dev/null +++ b/docs/dev_guide/topics/get-data.md @@ -0,0 +1,9 @@ +# Get data + +You can use the HERE Data SDK for C++ to get data from catalogs. The process of getting data from catalogs depends on the layer type. Currently, we only support getting data from versioned, volatile, and stream layers. Test. + +- [Get data from a versioned layer](../../dataservice-read-catalog-example.md#get-data-from-a-versioned-layer) +- [Get data from a versioned layer with a cache](../../dataservice-cache-example.md#get-data-from-a-versioned-layer-with-a-cache) +- [Get data from a volatile layer](get-data-from-volatile-layer.md) +- [Get data from a stream layer](../../dataservice-read-from-stream-layer-example.md#get-data-from-a-stream-layer) + diff --git a/docs/dev_guide/topics/get-partition-metadata.md b/docs/dev_guide/topics/get-partition-metadata.md new file mode 100644 index 000000000..426dd6168 --- /dev/null +++ b/docs/dev_guide/topics/get-partition-metadata.md @@ -0,0 +1,87 @@ +# Get partition metadata + +Partition metadata consists of the following information about the partition: + +- Data handle +- ID +- Version +- Data size +- Compressed data size +- Checksum + +**To get partition metadata:** + +1. Create the `OlpClientSettings` object. + + For instructions, see [Create platform client settings](../docs/create-platform-client-settings.md). + +2. Depending on the layer type, create a versioned or volatile layer client with the HERE Resource Name (HRN), layer ID, layer version, and platform client settings from step 1. + + If you do not specify a catalog version, the latest version is used. Depending on the fetch option that you specified in your first API call to the client, the `GetLatestVersion` method automatically gets the latest version in one of the following ways: + + - For the `OnlineIfNotFound` fetch option, queries the network, and if an error occurs, checks the cache. If the online version is higher than the cache version, the cache version is updated. + - For the `OnlineOnly` fetch option, only queries the network. + - For the `CacheOnly` fetch option, only checks the cache. + + ```cpp + olp::dataservice::read::VersionedLayerClient layer_client( + olp::client::HRN(kCatalogHRN), layer_id, version, client_settings); + ``` + +3. Create the `PartitionsRequest` object with one of the following fetch options: + + - (Default) To query network if the requested resource is not found in the cache, use `OnlineIfNotFound`. + - To skip cache lookups and query the network right away, use `OnlineOnly`. + - To return immediately if a cache lookup fails, use `CacheOnly`. + - (Not for `VersionedLayerClient`) To return the requested cached resource if it is found and update the cache in the background, use `CacheWithUpdate`. + + ```cpp + auto request = + olp::dataservice::read::PartitionsRequest() + .WithBillingTag("MyBillingTag") + .WithFetchOption( + olp::dataservice::read::FetchOptions::OnlineIfNotFound); + ``` + +4. Call `GetPartitions` method with the `PartitionRequest` parameter. + + ```cpp + auto future = layer_client.GetPartitions(request); + ``` + + > #### Note + > If your layer uses tile keys as partition IDs, this operation can fail because of the large amount of data. + +5. Wait for the `PartitionsResponse` future. + + ```cpp + olp::dataservice::read::PartitionsResponse partitions_response = + future.GetFuture().get(); + ``` + +The `PartitionsResponse` object holds the details of the completed operation and is used to determine operation success and access resultant data: + +- `IsSuccessful()` – if the operation is successful, returns `true`. Otherwise, returns `false`. +- `GetResult()` – if the operation is successful, returns the following resultant data: `olp::dataservice::read::PartitionsResult` +- `GetError()` – contains error information as a result of an error in the `olp::client::ApiError` object. + +```cpp +if (partitions_response.IsSuccessful()) { + const olp::dataservice::read::PartitionsResult& response_result = + partitions_response.GetResult(); + // Handle success +} else { + // Handle fail +} +``` + +The `PartitionsResult` class contains the `GetPartitions` method that returns a collection of partition metadata objects of the `olp::dataservice::read::model::Partition` type. + +The `Partition` class contains partition metadata and exposes the following members: + +- `GetChecksum` – returns partition checksum. +- `GetCompressedDataSize` – returns the size of the compressed partition data. +- `GetDataHandle` – returns the handle that can be used by the `GetData` function to retrieve the partition data. +- `GetDataSize` – returns the size of the partition data. +- `GetPartition` – returns the partition ID. +- `GetVersion` – returns the latest catalog version for the partition. \ No newline at end of file diff --git a/docs/dev_guide/topics/manage-eviction-protection.md b/docs/dev_guide/topics/manage-eviction-protection.md new file mode 100644 index 000000000..15fb76052 --- /dev/null +++ b/docs/dev_guide/topics/manage-eviction-protection.md @@ -0,0 +1,45 @@ +# Manage eviction protection + +You can add tile keys to a protected list if you do not want them to be evicted. +For example, you may want to protect tile keys of your home region so that they always stay in the cache and are not deleted when you travel to other places. +You can also remove tile keys from protection. + +**To work with eviction protection:** + +1. Create the `OlpClientSettings` object. + + For instructions, see [Create platform client settings](../../create-platform-client-settings.md). + +2. Create the `VersionedLayerClient` object with the HERE Resource Name (HRN) of the catalog that contains the layer, the layer ID, catalog version, and the platform client settings from step 1. + + > #### Note + > If a catalog version is not specified, the latest version is used. + + ```cpp + olp::dataservice::read::VersionedLayerClient layer_client ( + client::HRN catalog, + std::string layer_id, + boost::optional catalog_version, + client::OlpClientSettings settings); + ``` + +3. Depending on how you want to manage eviction protection, do one of the following: + + - If you want to protect tile keys from eviction, make sure that the `Release` method is not in progress, and then call the `Protect` method with the list of tile keys that you want to protect. + + > #### Note + > You can protect tile keys from eviction if their data handles are present in the cache at the time of the call. + + ```cpp + layer_client.Protect(); + ``` + + Data and keys of the specified tiles are added to the protected list and stored in the cache. The keys are removed from the LRU cache. Now, they cannot be evicted and do not expire. The quadtree stays protected if at least one tile key is protected. + + - If you want to remove tile keys from protection, make sure that the `Protect` method is not in progress, and then call the `Release` method with the list of tile keys that you want to remove from protection. + + ```cpp + layer_client.Protect(); + ``` + + Data and keys of the specified tiles are removed from the protected list. The keys are added to the LRU cache. Now, they can be evicted. Expiration value is restored, and keys can expire. The quadtree can be removed from the protected list if all tile keys are no longer protected. diff --git a/docs/dev_guide/topics/publish-data-to-index-layer.md b/docs/dev_guide/topics/publish-data-to-index-layer.md new file mode 100644 index 000000000..237223060 --- /dev/null +++ b/docs/dev_guide/topics/publish-data-to-index-layer.md @@ -0,0 +1,64 @@ +# Publish data to an index layer + +You can index and store metadata and data in a way that is optimized for batch processing in an [index layer](https://docs.here.com/data-api/docs/layers#index-layers). + +**To publish data to the index layer:** + +1. Create the `OlpClientSettings` object. + + For instructions, see [Create platform client settings](../../create-platform-client-settings.md). + +2. Create the `IndexLayerClient` object with the HERE Resource Name (HRN) of the catalog that contains the layer and the platform client settings from step 1. + + ```cpp + auto client = olp::dataservice::write::IndexLayerClient( + olp::client::HRN{kCatalogHRN}, client_settings); + ``` + +3. Create the `Index` object. + + ```cpp + Index index; + std::map> index_fields; + index_fields.insert(std::pair>( + "Place", + std::make_shared("New York", IndexType::String))); + index.SetIndexFields(index_fields); + ``` + +4. Create the `PublishIndexRequest` object with the data that you want to publish, layer ID, and index that you created in step 3. + + ```cpp + auto index_request = PublishIndexRequest() + .WithIndex(index) + .WithData(data) + .WithLayerId(layer_id); + ``` + +5. Call the `PublishIndex` method with the `DataRequest` parameter. + + ```cpp + auto future = client.PublishIndex(index_request); + ``` + +6. Wait for the `PublishIndexResponse` future. + + ```cpp + auto response = future.GetFuture().get(); + ``` + +The `PublishIndexResponse` object holds details of the completed operation and is used to determine operation success and access resultant data: + +- `IsSuccessful()` – if the operation is successful, returns `true`. Otherwise, returns `false`. +- `GetResult()`– if the operation is successful, returns the following resultant data: `olp::dataservice::write::PublishIndexResult` +- `GetError()` – contains error information as a result of an error in the `olp::client::ApiError` object. + +```cpp +if (response.IsSuccessful()) { + auto response_result = response.GetResult(); + // Handle success +} else { + auto api_error = response.GetError(); + // Handle fail +} +``` diff --git a/docs/dev_guide/topics/publish-data-to-versioned-layer.md b/docs/dev_guide/topics/publish-data-to-versioned-layer.md new file mode 100644 index 000000000..238da360e --- /dev/null +++ b/docs/dev_guide/topics/publish-data-to-versioned-layer.md @@ -0,0 +1,83 @@ +# Publish data to a versioned layer + +If you need to store and access the history of previous data updates, publish data to a [versioned layer](https://docs.here.com/data-api/docs/layers#versioned-layers). To achieve consistency between layers, publish any update that affects multiple versioned layers together in one publication. You can access a new catalog version when all layers are updated and the publication is finalized. Once you publish a version, you cannot change the data in that version and can remove it only by removing the whole catalog version. + +**To publish data to the versioned layer:** + +1. Create the `OlpClientSettings` object. + + For instructions, see [Create platform client settings](../../create-platform-client-settings.md). + +2. Create the `VersionedLayerClient` object with the HERE Resource Name (HRN) of the catalog that contains the layer and the platform client settings from step 1. + + ```cpp + auto versioned_client = olp::dataservice::write::VersionedLayerClient( + olp::client::HRN{kCatalogHRN}, client_settings); + ``` + +3. Create the `StartBatchRequest` object with the layer ID. + + ```cpp + auto start_batch_request = StartBatchRequest().WithLayers(kLayer); + ``` + +4. Run the `StartBatchRequest` method and wait for the response. + + ```cpp + auto start_batch_response = + versioned_client.StartBatch(start_batch_request).GetFuture().get(); + ``` + +5. Get details of the started batch with the `Publication` parameter. + + ```cpp + auto get_batch_response = + versioned_client.GetBatch(start_batch_response.GetResult()) + .GetFuture() + .get(); + ``` + +6. Create the `PublishPartitionDataRequest` object with the data that you want to publish, layer ID, and partition ID. + + ```cpp + auto publish_request = + PublishPartitionDataRequest() + .WithData(std::make_shared>(20, 0x30)) + .WithLayerId(kLayer) + .WithPartitionId(kPartition); + ``` + +7. Run the `PublishToBatch` method with the `Publication` and the `PublishRequest` parameters, and wait for the response. + + ```cpp + auto publish_to_batch_response = + versioned_client + .PublishToBatch(start_batch_response.GetResult(), publish_request) + .GetFuture() + .get(); + ``` + +8. Run the `CompleteBatch` method with the publication details, and wait for the response. + + ```cpp + auto complete_batch_response = + versioned_client->CompleteBatch(get_batch_response.GetResult()) + .GetFuture() + .get(); + ``` + +The `PublishDataResponse` object holds details of the completed operation and is used to determine operation success and access resultant data: + +- `IsSuccessful()` – if the operation is successful, returns `true`. Otherwise, returns `false`. +- `GetResult()`– if the operation is successful, returns the following resultant data: `olp::dataservice::write::PublishDataResult` +- `GetError()` – contains error information as a result of an error in the `olp::client::ApiError` object. + +```cpp +if (response.IsSuccessful()) { + auto response_result = response.GetResult(); + // Handle success +} else { + auto api_error = response.GetError(); + // Handle fail +} +``` diff --git a/docs/dev_guide/topics/publish-data-to-volatile-layer.md b/docs/dev_guide/topics/publish-data-to-volatile-layer.md new file mode 100644 index 000000000..a7e519d6c --- /dev/null +++ b/docs/dev_guide/topics/publish-data-to-volatile-layer.md @@ -0,0 +1,50 @@ +# Publish data to a volatile layer + +If you need to store only the current version of data, use a [volatile layer](https://docs.here.com/data-api/docs/layers#volatile-layers). As new data is published to the volatile layer, old data is overwritten. + +**To publish data to the volatile layer:** + +1. Create the `OlpClientSettings` object. + + For instructions, see [Create platform client settings](../../create-platform-client-settings.md). + +2. Create the `VolatileLayerClient` object with the HERE Resource Name (HRN) of the catalog that contains the layer and the platform client settings from step 1. + + ```cpp + auto client = olp::dataservice::write::VolatileLayerClient( + olp::client::HRN{kCatalogHRN}, client_settings); + ``` + +3. Create the `PublishPartitionDataRequest` object with the data that you want to publish, layer ID, and partition ID. + + ```cpp + auto request = PublishPartitionDataRequest().WithData(buffer).WithLayerId(kLayer).WithPartitionId(kPartition); + ``` + +4. Call the `PublishPartitionData` method with the `DataRequest` parameter. + + ```cpp + auto futureResponse = client.PublishPartitionData(request); + ``` + +5. Wait for the `PublishPartitionDataResponse` future. + + ```cpp + auto response = futureResponse.GetFuture().get(); + ``` + +The `PublishDataResponse` object holds details of the completed operation and is used to determine operation success and access resultant data: + +- `IsSuccessful()` – if the operation is successful, returns `true`. Otherwise, returns `false`. +- `GetResult()`– if the operation is successful, returns the following resultant data: `olp::dataservice::write::PublishDataResult` +- `GetError()` – contains error information as a result of an error in the `olp::client::ApiError` object. + +```cpp +if (response.IsSuccessful()) { + auto response_result = response.GetResult(); + // Handle success +} else { + auto api_error = response.GetError(); + // Handle fail +} +``` diff --git a/docs/dev_guide/topics/publish-data.md b/docs/dev_guide/topics/publish-data.md new file mode 100644 index 000000000..edfb57f42 --- /dev/null +++ b/docs/dev_guide/topics/publish-data.md @@ -0,0 +1,8 @@ +# Publish data + +You can use the HERE Data SDK for C++ to publish data to catalogs. The process of publishing data to catalogs depends on the layer type. + +- [Publish data to a versioned layer](publish-data-to-versioned-layer.md) +- [Publish data to a volatile layer](publish-data-to-volatile-layer.md) +- [Publish data to a stream layer](../../dataservice-write-example.md#publish-data-to-a-stream-layer) +- [Publish data to an index layer](publish-data-to-index-layer.md) diff --git a/docs/dev_guide/topics/run-examples.md b/docs/dev_guide/topics/run-examples.md new file mode 100644 index 000000000..0d63bc992 --- /dev/null +++ b/docs/dev_guide/topics/run-examples.md @@ -0,0 +1,7 @@ +# Run the examples + +The HERE Data SDK for C++ contains several example programs that demonstrate some of the key use cases. These example programs can be found in the **examples** folder: + +- [Read example](https://github.com/heremaps/here-data-sdk-cpp/blob/master/docs/dataservice-read-catalog-example.md) – demonstrates how to get catalog and partition metadata, as well as partition data. +- [Cache example](https://github.com/heremaps/here-data-sdk-cpp/blob/master/docs/dataservice-cache-example.md) – demonstrates how to get partition data and work with a mutable and protected cache. +- [Write example](https://github.com/heremaps/here-data-sdk-cpp/blob/master/docs/dataservice-write-example.md) – demonstrates how to publish data to OLP. diff --git a/docs/dev_guide/topics/technical-details-and-prerequisites.md b/docs/dev_guide/topics/technical-details-and-prerequisites.md new file mode 100644 index 000000000..5bcae29a2 --- /dev/null +++ b/docs/dev_guide/topics/technical-details-and-prerequisites.md @@ -0,0 +1,5 @@ +# Details and prerequisites + +To get catalog and partition metadata, as well as to get data from and publish data to the HERE platform, you need to set up the platform client as described in [Create platform client settings](../../create-platform-client-settings.md). + +You can also get and change cache size. To learn more, see [Work with a cache](work-with-cache.md). diff --git a/docs/dev_guide/topics/use-cases.md b/docs/dev_guide/topics/use-cases.md new file mode 100644 index 000000000..1a5d81e68 --- /dev/null +++ b/docs/dev_guide/topics/use-cases.md @@ -0,0 +1,19 @@ +# Use cases + +This section describes the most common cases when HERE Data SDK for C++ can be used: + +- [Authenticate to the HERE platform](../../authenticate.md) +- [Manage eviction protection](manage-eviction-protection.md) +- [Get catalog metadata](../../dataservice-read-catalog-example.md#get-catalog-metadata) +- [Get partition metadata](../../dataservice-read-catalog-example.md#get-partition-metadata) +- [Get data](get-data.md) + - [Get data from a versioned layer](../../dataservice-read-catalog-example.md#get-data-from-a-versioned-layer) + - [Get data from a versioned layer with a cache](../../dataservice-cache-example.md#get-data-from-a-versioned-layer-with-a-cache) + - [Get data from a volatile layer](get-data-from-volatile-layer.md) + - [Get data from a stream layer](../../dataservice-read-from-stream-layer-example.md#get-data-from-a-stream-layer) +- [Publish data](publish-data.md) + - [Publish data to a versioned layer](publish-data-to-versioned-layer.md) + - [Publish data to a volatile layer](publish-data-to-volatile-layer.md) + - [Publish data to a stream layer](../../dataservice-write-example.md#publish-data-to-a-stream-layer) + - [Publish data to an index layer](publish-data-to-index-layer.md) +- [Work with unsupported REST Data APIs](../../work-with-data-apis.md) diff --git a/docs/dev_guide/topics/work-with-cache.md b/docs/dev_guide/topics/work-with-cache.md new file mode 100644 index 000000000..90bab50fa --- /dev/null +++ b/docs/dev_guide/topics/work-with-cache.md @@ -0,0 +1,28 @@ +# Work with a cache + +You can configure a cache instance and add it to the `OlpClientSettings` instance. Otherwise, a default cache of 1 MB is automatically created and cached in memory when you create one of the following clients: `VersionedLayerClient`, `VolatileLayerClient`, `StreamLayerClient`, or `IndexLayerClient`. + +For information on how to configure cache settings, see [Create platform client settings](../../create-platform-client-settings.md). + +If your application is running with the cache, you can get or change cache size: + +- To get the cache size, call the `Size` method with the needed cache type. + + ```cpp + auto cache = + olp::client::OlpClientSettingsFactory::CreateDefaultCache(cache_settings); + auto cache_mutable_size = cache->Size(olp::cache::DefaultCache::kMutable); + ``` + +- To change the cache size, call the `Size` method with the new size in bytes. + + > #### Note + > You can only change the size of the mutable cache. + + ```cpp + auto cache = + olp::client::OlpClientSettingsFactory::CreateDefaultCache(cache_settings); + auto bytes_evicted = cache->Size(512); + ``` + + If the new cache size is smaller than the current size, items are evicted until the cache shrinks to the specified capacity, and you get the size of the evicted data. If the new size is greater, you get `0u`. diff --git a/docs/get-started.md b/docs/get-started.md index a05e9f746..16a0f1a17 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -30,18 +30,18 @@ For the terms and conditions covering this documentation, see the [HERE Document To use HERE Data SDK for C++, you need to understand the following concepts related to the HERE platform: -- [Catalogs](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/catalogs.html) -- [Layers](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/layers.html) -- [Partitions](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/partitions.html) -- [HERE Resource Names (HRNs)](https://www.here.com/docs/bundle/data-api-developer-guide/page/rest/hrn.html) +- [Catalogs](https://docs.here.com/data-api/docs/catalogs) +- [Layers](https://docs.here.com/data-api/docs/layers) +- [Partitions](https://docs.here.com/data-api/docs/getting-partition-metadata) +- [HERE Resource Names (HRNs)](https://docs.here.com/data-api/docs/get-apis-for-an-hrn) -For more details, see the [Data API Developer Guide](https://www.here.com/docs/bundle/data-api-developer-guide/page/README.html). +For more details, see the [Data API Developer Guide](https://docs.here.com/data-api/docs/data-api-intro). ## Get credentials To work with catalog or service requests to the HERE platform, you need to get authentication and authorization credentials. -You can authenticate to the HERE platform within your application with the platform credentials available on the HERE Portal by means of Data SDK for C++ authentication library. For the available authentication options, see the [Identity and Access Management Developer Guide](https://www.here.com/docs/bundle/identity-and-access-management-developer-guide/page/README.html). +You can authenticate to the HERE platform within your application with the platform credentials available on the HERE Portal by means of Data SDK for C++ authentication library. For the available authentication options, see the [Identity and Access Management Developer Guide](https://docs.here.com/identity-and-access-management/docs/readme). ## Install the SDK diff --git a/docs/work-with-data-apis.md b/docs/work-with-data-apis.md index 4d727a4b9..e542badcd 100644 --- a/docs/work-with-data-apis.md +++ b/docs/work-with-data-apis.md @@ -17,7 +17,7 @@ The example below demonstrates how to use the `olp::client::OlpClient` class fro - Use a base URL: 1. Get the base URL from the lookup API service. - For instructions, see the [API Lookup API Developer's Guide](https://www.here.com/docs/bundle/api-lookup-api-developer-guide/page/README.html) + For instructions, see the [API Lookup API Developer's Guide](https://docs.here.com/data-api/docs/readme-api-lookup-developer-guide) 2. Create an `OlpClient` instance with the client settings from step 1 and the base URL.