Create a HERE Platform data application

The Data Client Library allows you to create HERE platform data applications. The instructions below illustrate the process for a basic application using the Scala Build Tool (SBT) and Maven.

Access credentials

You need two types of credentials:

1. Platform credentials -- To obtain your platform credentials, create a new application via the https://platform.here.com/profile/apps-and-keys page. When you have created your application, click on the Create A Key button to download these credentials. Place the credentials in $HOME/.here/credentials.properties.
2. Repository Credentials -- To obtain your credentials to access the repository containing the Data Client Library, go to https://platform.here.com/portal/profile/repository and click on Create credentials, to download the settings.xml file.

Note

For detailed instructions on how to obtain your platform and repository credentials, see the Identity & Access Management Developer Guide.

Configure the build system

The following steps describe how to configure SBT and Maven projects.

For SBT, create a new file in ~/.ivy2/.credentials with the following content:

realm=Artifactory Realm
host=repo.platform.here.com
user=[REPOSITORY_USERNAME]
password=[REPOSITORY_PASSWORD]

where [REPOSITORY_USERNAME] and [REPOSITORY_PASSWORD] are the username and password from the downloaded settings.xml. You can find this information in the servers/server[1] XML node.

For Maven, copy the downloaded settings.xml to ~/.m2.

Create a project

Create a new empty project directory with one of the following files: build.sbt for SBT or pom.xml for Maven.

scalaVersion := "2.13.16" // data client library currently only supports Scala 2.13
credentials += Credentials(Path.userHome / ".ivy2" / ".credentials")
resolvers += "HERE Repo" at "https://repo.platform.here.com/artifactory/open-location-platform/"
libraryDependencies ++= Seq(
  "com.here.platform.data.client" %% "data-engine" % "1.22.33"
)

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.company</groupId>
    <artifactId>olp-data-sample</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>com.here.platform.data.client</groupId>
            <artifactId>data-engine_2.13</artifactId>
            <version>1.22.33</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.7.0</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

You have now completed your project configuration and can start using the Data Client Library APIs.

The code example below shows a simple class that prints the HERE Resource Names (HRNs) for catalogs that you have access to on the HERE platform.

Add the file containing the class to the appropriate directory in src/main/scala or src/main/java, in your project:

import org.apache.pekko.actor.CoordinatedShutdown.UnknownReason
import org.apache.pekko.actor.{ActorSystem, CoordinatedShutdown}
import com.here.platform.data.client.scaladsl.DataClient

import scala.concurrent.ExecutionContextExecutor
import scala.util.{Failure, Success}

object OverviewScalaMain {

  def main(args: Array[String]): Unit = {
    implicit val actorSystem: ActorSystem = ActorSystem()
    implicit val dispatcher: ExecutionContextExecutor = actorSystem.dispatcher

    val dataClient = DataClient()
    val adminApi = dataClient.adminApi()

    // Now you can start using the API
    adminApi
      .listCatalogs()
      .andThen {
        case Success(catalogHRNs) => catalogHRNs.foreach(println(_))
        case Failure(e) => e.printStackTrace()
      }
      .andThen {
        case _ => CoordinatedShutdown(actorSystem).run(UnknownReason)
      }
  }
}

import com.here.platform.data.client.javadsl.AdminApi;
import com.here.platform.data.client.javadsl.DataClient;
import org.apache.pekko.actor.ActorSystem;
import org.apache.pekko.actor.CoordinatedShutdown;

public class OverviewJavaMain {

  public static void main(String[] args) {
    ActorSystem actorSystem = ActorSystem.create();

    DataClient dataClient = DataClient.get(actorSystem);
    AdminApi adminApi = dataClient.adminApi();

    // Now you can start using the API
    adminApi
        .listCatalogs()
        .whenComplete(
            (catalogHRNs, e) -> {
              if (catalogHRNs != null) {
                catalogHRNs.forEach(System.out::println);
              } else if (e != null) {
                e.printStackTrace();
              }
            })
        // When done, shutdown the Data Client through the ActorSystem
        .thenAccept(
            unbound ->
                CoordinatedShutdown.get(actorSystem).run(CoordinatedShutdown.unknownReason()));
  }
}

Pekko dependency

The Data Client Library runs on top of Pekko Actors and Pekko Streams, using the ActorSystem to manage resources (threads, connection pools, and others). This means that your client needs to instantiate the ActorSystem and shut it down accordingly.

The ActorSystem is a heavyweight structure that allocates 1…N Threads; create one per logical application.

When you are sure that your application has completed all of its tasks, shut down the ActorSystem by invoking CoordinatedShutdown as shown in the examples above. The Data Client Library attaches additional cleanup tasks to CoordinatedShutdown that won't be run if you call the ActorSystem terminate method directly, so make sure to use the former.

Note In the following sections, references to myActorSystem and myMaterializer refer to the application-wide ActorSystem and Materializer that you manage.

Implications of the Data Client Library's streaming behavior

The Data Client Library interprets data as streams, which means that the back-pressure mechanisms enabled by your client are exposed through all layers: from the TCP layer, all the way up to the developer-facing APIs.

Note Your client must consume the Data Client Library responses. Otherwise, the Data Client Library assumes the incoming data should remain back-pressured and stalls the incoming data via TCP back-pressure mechanisms.

Scala vs Java

The Data Client Library supports both Java and Scala bindings, many classes have both javadsl and scaladsl implementations. If the class package does not include a specific Domain Specific Language (DSL), this means that the class package has getters and setters available for both Scala and Java.

Since the Data Client Library runs on top of Pekko, many public APIs expose Pekko classes, such as Source, Sink, or Flow. If you are not familiar with Pekko Streams, you can use overloaded methods in the Data Client Library that expose Scala or Java native classes, such as Iterator, List, or Seq.

Error handling

The Data Client Library operations could throw following two main types of exceptions: DataClientRetriableException - The base class of retriable exceptions returned through the Data Client Library. DataClientNonRetriableException - The base class of non-retriable exceptions returned through the Data Client Library.

Artifacts

libraryDependencies += "com.here.platform.data.client" % "{data-client-module}" % "1.22.33"

<dependency>
  <groupId>com.here.platform.data.client</groupId>
  <artifactId>{data-client-module}</artifactId>
  <version>1.22.33</version>
</dependency>

dependencies {
  compile group: 'com.here.platform.data.client', name: '{data-client-module}', version: '1.22.33'
}