Read data from versioned catalogs other than Location Library

The High-Level API chapter explains how to work with Optimized Map for Location Library catalogs.

In some cases, you might want to read from other catalogs that are not an Optimized Map for Location Library and cannot be opened using the OptimizedMapCatalog described in High-Level API.

In this case, you can use the data-client-v2 API to open the catalog and set up the necessary decoders for the layers you want to read while still benefiting from the cache mechanism described earlier.

The functionalities below will need the following dependency:

libraryDependencies ++= Seq(
  "com.here.platform.data.client.v2" %% "data-client-v2-main" % "DATA_CLIENT_V2_VERSION"
)

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

dependencies {
    compile group: 'com.here.platform.data.client.v2', name: 'data-client-v2-main_2.13', version:'DATA_CLIENT_V2_VERSION'
}

How to read from version layers such as Here Map Content

When you need to open a catalog that is not an Optimized Map for Location Library, you should use the data-client-v2 API. This API is more low-level than the OptimizedMapCatalog and requires you to explicitly specify the layers to decode, the corresponding decoders and if necessary, weighers to manage cache size.

The following example demonstrates how to open a Here Map Content catalog and set up decoders for two layers using the data-client-v2 API:

topology-attributes using here tile partitioning scheme
indexed-locations using generic partitioning scheme

import com.here.platform.data.client.base.scaladsl.BaseClient
import com.here.platform.data.client.v2.api.scaladsl.versioned._
import com.here.platform.data.client.v2.caching.scaladsl.versioned._
import com.here.platform.data.client.v2.main.scaladsl.{DataClient, DataClientCatalog}
import com.here.platform.location.integration.heremapcontent.HereMapContent
import com.here.schema.rib.v2.indexed_locations_partition.IndexedLocationsPartition
import com.here.schema.rib.v2.topology_attributes_partition.TopologyAttributesPartition

val baseClient = BaseClient()
val hmcCatalog: DataClientCatalog =
  DataClient(baseClient)
    .catalogBuilder(HereMapContent.v2.HRN)
    .withVersionedLayerReadersConfiguration(
      VersionedLayerReadersConfiguration()
        .withLayer(
          "topology-attributes",
          VersionedLayerReaderConfiguration(is => TopologyAttributesPartition.parseFrom(is))
            .withWeigher(partition =>
              // write here your weigher based on the content of partition in bytes (as cache size is given in bytes below)
              partition.serializedSize * 3)
        )
        .withLayer(
          "indexed-locations",
          VersionedLayerReaderConfiguration(is => IndexedLocationsPartition.parseFrom(is))
            .withWeigher(partition =>
              // write here your weigher based on the content of partition in bytes (as cache size is given in bytes below)
              partition.serializedSize * 4)
        )
        .withMaxWeight(100 * 1024 * 1024) // 100 MB total cache size
    )
    .build

val versionedLayers: VersionedLayers = hmcCatalog.versionedLayers

val topologyAttributesLayer: VersionedHereTileLayer =
  versionedLayers.versionedHereTileLayer("topology-attributes")
val topologyAttributesLayerReader: VersionedHereTileLayerReader[TopologyAttributesPartition] =
  topologyAttributesLayer.reader[TopologyAttributesPartition]

val indexedLocationsLayer: VersionedGenericLayer =
  versionedLayers.versionedGenericLayer("indexed-locations")
val indexedLocationsLayerReader: VersionedGenericLayerReader[IndexedLocationsPartition] =
  indexedLocationsLayer.reader[IndexedLocationsPartition]

import com.here.platform.data.client.base.javadsl.BaseClient;
import com.here.platform.data.client.base.javadsl.BaseClientJava;
import com.here.platform.data.client.v2.api.javadsl.versioned.*;
import com.here.platform.data.client.v2.caching.javadsl.versioned.VersionedLayerReaderConfiguration;
import com.here.platform.data.client.v2.caching.javadsl.versioned.VersionedLayerReadersConfiguration;
import com.here.platform.data.client.v2.main.javadsl.DataClient;
import com.here.platform.data.client.v2.main.javadsl.DataClientCatalog;
import com.here.platform.location.integration.heremapcontent.HereMapContent;
import com.here.schema.rib.v2.IndexedLocationsPartitionOuterClass.IndexedLocationsPartition;
import com.here.schema.rib.v2.TopologyAttributesPartitionOuterClass.TopologyAttributesPartition;
BaseClient baseClient = BaseClientJava.instance();
DataClientCatalog dataClientCatalog =
    new DataClient(baseClient)
        .catalogBuilder(HereMapContent.v2.HRN)
        .withVersionedLayerReadersConfiguration(
            new VersionedLayerReadersConfiguration()
                .withLayer(
                    "topology-attributes",
                    new VersionedLayerReaderConfiguration<>(
                            is -> TopologyAttributesPartition.parseFrom(is))
                        .withWeigher(
                            partition ->
                                // write here your weigher based on the content of partition in
                                // bytes (as cache size is given in bytes below)
                                partition.getSerializedSize() * 3))
                .withLayer(
                    "indexed-locations",
                    new VersionedLayerReaderConfiguration<>(
                            is -> IndexedLocationsPartition.parseFrom(is))
                        .withWeigher(
                            partition ->
                                // write here your weigher based on the content of partition in
                                // bytes (as cache size is given in bytes below)
                                partition.getSerializedSize() * 4))
                .withMaxWeight(100 * 1024 * 1024) // 100 MB total cache size
            )
        .build();

VersionedLayers versionedLayers = dataClientCatalog.getVersionedLayers();

VersionedHereTileLayer topologyAttributesLayer =
    versionedLayers.getVersionedHereTileLayer("topology-attributes");
VersionedHereTileLayerReader<TopologyAttributesPartition> topologyAttributesLayerReader =
    topologyAttributesLayer.getReader();

VersionedGenericLayer indexedLocationsLayer =
    versionedLayers.getVersionedGenericLayer("indexed-locations");
VersionedGenericLayerReader<IndexedLocationsPartition> indexedLocationsLayerReader =
    indexedLocationsLayer.getReader();

How to resolve catalog versions

The CatalogVersionInfo class provides information about the versions of a catalog. For more details, see the documentation for java or scala.

Suppose you have two CatalogVersionInfo objects, one for Here Map Content and another for Optimized Map for Location Library.
You can open Here Map Content catalog as described above and Optimized Map for Location Library can be opened in the same way or as described in open an optimized map for location libraries section of High-Level API. The important thing is to have a CatalogVersionInfo object for each catalog.

import com.here.platform.data.client.base.scaladsl.BaseClient
import com.here.platform.data.client.v2.api.scaladsl.CatalogVersionInfo
import com.here.platform.data.client.v2.main.scaladsl.DataClient
import com.here.platform.location.integration.heremapcontent.HereMapContent
import com.here.platform.location.integration.optimizedmap.OptimizedMap
import com.here.platform.location.integration.optimizedmap.dcl2.OptimizedMapCatalog

val baseClient = BaseClient()

val hmcCatalog =
  DataClient(baseClient).catalogBuilder(HereMapContent.v2.HRN).build
val hmcCatalogVersionInfo: CatalogVersionInfo = hmcCatalog.versionInfo

val optimizedMapCatalog =
  OptimizedMapCatalog.from(OptimizedMap.v2.HRN).usingBaseClient(baseClient).newInstance
val optimizedMapVersionInfo: CatalogVersionInfo = optimizedMapCatalog.versionInfo

import com.here.hrn.HRN;
import com.here.platform.data.client.base.javadsl.BaseClient;
import com.here.platform.data.client.base.javadsl.BaseClientJava;
import com.here.platform.data.client.v2.api.javadsl.CatalogVersionInfo;
import com.here.platform.data.client.v2.main.javadsl.DataClient;
import com.here.platform.data.client.v2.main.javadsl.DataClientCatalog;
import com.here.platform.location.integration.optimizedmap.dcl2.javadsl.OptimizedMapCatalog;
BaseClient baseClient = BaseClientJava.instance();

DataClientCatalog hmcCatalog =
    new DataClient(baseClient).catalogBuilder(hereMapContentHRN).build();
CatalogVersionInfo hmcCatalogVersionInfo = hmcCatalog.getVersionInfo();

OptimizedMapCatalog optimizedMapCatalog =
    OptimizedMapCatalog.from(optimizedMapHRN).usingBaseClient(baseClient).newInstance();
CatalogVersionInfo optimizedMapVersionInfo = optimizedMapCatalog.versionInfo();

Find latest version of a catalog

Once you have a CatalogVersionInfo object you can easily find the latest version of a catalog as follows:

val latestHmcVersion: Option[Long] = hmcCatalogVersionInfo.latestVersion
val latestOmVersion: Option[Long] = optimizedMapVersionInfo.latestVersion

OptionalLong latestHmcVersion = hmcCatalogVersionInfo.latestVersion();
OptionalLong latestOmVersion = optimizedMapVersionInfo.latestVersion();

Find catalog dependencies

Every catalog has direct and un-direct dependencies, which you can list and filter given a catalog version as follows:

optimizedMapVersionInfo.dependencies(latestOmVersion.get).foreach(println)

optimizedMapVersionInfo
    .dependencies(latestOmVersion.getAsLong())
    .forEachRemaining(System.out::println);

Find the dependencies of a catalog given a version

If you want to find a version of Here Map Content with data compatible to Optimized Map for Location Library, you can either filter the output of dependencies method or use the higher level method resolveDependencyVersion:

val hmcVersion =
  optimizedMapVersionInfo.resolveDependencyVersion(latestOmVersion.get, HereMapContent.v2.HRN)

OptionalLong hmcVersion =
    optimizedMapVersionInfo.resolveDependencyVersion(
        latestOmVersion.getAsLong(), hereMapContentHRN);

Find the version of a compatible catalog

Suppose you have a catalog a that depends on another catalog b and a catalog c that also depends on b. Given a version v of a you can get all the versions of c that are compatible with a (for version v) and optionally share a common ancestor b as follows:

val cCompatibleVersions: Iterator[Long] =
  aCatalogVersionInfo.resolveCompatibleVersions(aVersion, cHrn, Seq(bHrn))

Iterator<Long> cCompatibleVersions =
    aCatalogVersionInfo.resolveCompatibleVersions(aVersion, cHrn, Arrays.asList(bHrn));

As a simpler example, if you are working with Here Map Content and you want to get a compatible version of Optimized Map for Location Library, you can proceed as follows:

val compatibleOptimizedMapVersions: Iterator[Long] =
  hmcCatalogVersionInfo.resolveCompatibleVersions(hmcCatalogVersionInfo.latestVersion.get,
                                                  OptimizedMap.v2.HRN)

Iterator<Long> compatibleOptimizedMapVersions =
    hmcCatalogVersionInfo.resolveCompatibleVersions(
        latestHmcVersion.getAsLong(), optimizedMapHRN);

Updated 21 days ago