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:

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.
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.61"
)

<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.61</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.61"

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

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