Create an 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.hereolp.cn/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.hereolp.cn/profile/repository and click on Create credentials, to download the settings.xml file.

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.hereolp.cn
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.12.17" // data client library currently only supports Scala 2.12
credentials += Credentials(Path.userHome / ".ivy2" / ".credentials")
resolvers += "HERE Repo" at "https://repo.platform.hereolp.cn/artifactory/open-location-platform/"
libraryDependencies ++= Seq(
  "com.here.platform.data.client" %% "data-engine" % "1.18.173"
)

<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.12</artifactId>
            <version>1.18.173</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.7.0</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</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 akka.actor.CoordinatedShutdown.UnknownReason
import akka.actor.{ActorSystem, CoordinatedShutdown}
import com.here.platform.data.client.scaladsl.DataClient

import scala.util.{Failure, Success}

object OverviewScalaMain {

  def main(args: Array[String]): Unit = {
    implicit val actorSystem = ActorSystem()
    implicit val dispatcher = 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 akka.actor.ActorSystem;
import akka.actor.CoordinatedShutdown;
import com.here.platform.data.client.javadsl.AdminApi;
import com.here.platform.data.client.javadsl.DataClient;

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()));
  }
}

Akka Dependency

The Data Client Library runs on top of Akka Actors and Akka 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 ActorMaterializer 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 Akka, many public APIs expose Akka classes, such as Source, Sink, or Flow. If you are not familiar with Akka 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.18.173"

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

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