Verify your credentials and access a catalog

Objectives: Verify that you set up the platform credentials and the Maven settings correctly, and introduce the concepts of HRN, Catalogs, Layers, and Metadata.

Complexity: Beginner

Time to complete: 20 min

Prerequisites: Verify Maven Settings

Source code: Download

This section demonstrates how to write a program that queries catalog information from the HERE Map Content data catalog (hrn: hrn:here:data::olp-here:rib-2).

After running this example successfully, you can be assured that your repository credentials and the platform credentials are set up correctly.

You can create this project in the verify-credentials folder, using the same structure and pom from the previous tutorial.

The following dependencies are needed for this example:

<dependencies>
    <dependency>
        <groupId>com.here.platform.data.client</groupId>
        <artifactId>data-client_${scala.compat.version}</artifactId>
    </dependency>
</dependencies>

To gather some metadata about a catalog, create some code in Scala or Java in the source folder.

If you have not generated your repository settings or platform credentials yet, see Get Credentials. After you have followed these instructions, you should have both a settings.xml with repository credentials, and a credentials.properties with platform credentials.

The program queries the HERE Map Content catalog (the catalog with all the traditional HERE map data) to get the latest available version, and some metadata associated with the catalog such as issue date, available layers, and the list of direct dependencies with the input catalogs you used to create this catalog).

/*
 * Copyright (c) 2018-2023 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.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import akka.actor.CoordinatedShutdown.UnknownReason
import akka.actor.{ActorSystem, CoordinatedShutdown}
import com.here.hrn.HRN
import com.here.platform.data.client.scaladsl.DataClient

import scala.concurrent._
import scala.concurrent.duration._

object CatalogInfoScala extends App {

  // Initialize the Akka Actor System used by the Data Client Library
  implicit lazy val actorSystem = ActorSystem()

  // The Here Map Content identifier is an HRN (Here Resource Name)
  // Please, use hrn:here-cn:data::olp-cn-here:here-map-content-china-2 for China environment
  private val hereMapContentHrn = HRN("hrn:here:data::olp-here:rib-2")

  // Initialize the query API for the catalog
  val queryApi = DataClient().queryApi(hereMapContentHrn)

  // Get the latest available catalog version
  val latestVersion = Await.result(queryApi.getLatestVersion(), 30 seconds)

  // Retrieve more metadata for the version, if any
  latestVersion match {
    case Some(version) =>
      println(s"The latest Here Map Content version is $version")
      val latestVersionInfo = Await.result(queryApi.getVersion(version), 30 seconds)
      println(s"The catalog was last updated on ${new java.util.Date(latestVersionInfo.timestamp)}")

      println("And was reportedly compiled out of these input catalogs:")
      latestVersionInfo.dependencies.filter(_.direct).foreach { dependency =>
        println(s"  ${dependency.hrn} ${dependency.version}")
      }

    case None =>
      println("No version for this catalog")
  }

  // In production code this would be in a finally block
  val shutdown = CoordinatedShutdown(actorSystem).run(UnknownReason)
  Await.result(shutdown, Duration.Inf)
}

/*
 * Copyright (c) 2018-2023 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.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import static java.lang.System.out;

import akka.actor.ActorSystem;
import akka.actor.CoordinatedShutdown;
import com.here.hrn.HRN;
import com.here.platform.data.client.javadsl.DataClient;
import com.here.platform.data.client.javadsl.QueryApi;
import com.here.platform.data.client.model.VersionDependency;
import java.util.OptionalLong;

public class CatalogInfoJava {

  public static void main(String[] args) {

    // Initialize the Akka Actor System used by the Data Client Library
    ActorSystem actorSystem = ActorSystem.create();

    // The Here Map Content identifier is an HRN (Here Resource Name)
    // Please, use hrn:here-cn:data::olp-cn-here:here-map-content-china-2 for China environment
    HRN hereMapContentHrn = HRN.fromString("hrn:here:data::olp-here:rib-2");

    // Initialize the query API for the catalog
    QueryApi queryApi = DataClient.get(actorSystem).queryApi(hereMapContentHrn);

    // Get the latest available catalog version
    queryApi
        .getLatestVersion(OptionalLong.empty())
        .thenAccept(
            version -> {
              if (version.isPresent()) {
                out.println("The latest Here Map Content version is " + version.getAsLong());
                queryApi
                    .getVersion(version.getAsLong())
                    .thenAccept(
                        versionInfo -> {
                          out.println(
                              "The catalog was last updated on "
                                  + new java.util.Date(versionInfo.getTimestamp()));
                          out.println("And was reportedly compiled out of these input catalogs:");
                          versionInfo
                              .getDependencies()
                              .stream()
                              .filter(VersionDependency::isDirect)
                              .forEach(
                                  dependency ->
                                      out.println(
                                          "  "
                                              + dependency.getHrn()
                                              + " "
                                              + dependency.getVersion()));
                        })
                    .toCompletableFuture()
                    .join();
              } else {
                out.println("No version for this catalog");
              }
            })
        .toCompletableFuture()
        .join();

    // In production code this would be in a finally block
    CoordinatedShutdown.get(actorSystem)
        .runAll(CoordinatedShutdown.unknownReason())
        .toCompletableFuture()
        .join();
  }
}

You can now run your code either using your IDE, or from the command line using mvn:

mvn compile exec:java -Dexec.mainClass=CatalogInfoScala

mvn compile exec:java -Dexec.mainClass=CatalogInfoJava

The expected output should look like this, with the confirmation that your code was successful in fetching the token:

[INFO] [...] [CatalogInfoJava.main()] [DataClientSettingsExt] Reading credentials from default credentials file XXXX
[INFO] [...] [default-akka.actor.default-dispatcher-5] [HereAccountProvider] OAuth token fetched successfully with expiration of 86399s, next refresh scheduled in 57599s.
The latest Here Map Content version is 32
The catalog was last updated on Sat May 26 10:14:24 CEST 2018
And was reportedly compiled out of these input catalogs:
  hrn:here:data::olp-here:tailgate-2 28
  hrn:here:datastore::olp-here:os-rib-address-global-1 221
  hrn:here:datastore::olp-here:os-rib-carto-global-1 222
  hrn:here:datastore::olp-here:os-rib-street-global-1 217

The output lists the input catalog HRNs, together with their respective versions.

Further information

The Data Client Library is a complete API for accessing the Data Service. You can use this API to query the catalog metadata (versions, layers, partitions inside the layers) and data (actual partition payload). For more details, see Data Client Library Developer Guide.

The Data Client Library documentation covers more detailed workflows such as how to introspect more metadata fields, fetching data from partitions, and examining content changes between versions.

The following sections explain how to create your own catalog and layers and explore the available layer types and configurations:

• The Data API documentation provides information about the available layer types and configurations.
• The OLP CLI documentation and the Data section of the portal explain the interactive querying and manipulation of catalogs.
• The Data Client Library Developer Guide describes the Scala and Java APIs that can access the services.

Once you have verified your platform credentials to access the HERE Map Content, you can implement a simple batch pipeline to process catalog data in Spark.