heremaps / here-artifact-maven-wagon

The HERE platform Maven Wagon plugin provides Java and Scala developers with access to platform artifacts via Maven

HERE platform Maven Wagon plugin

Introduction

The HERE platform Maven Wagon plugin provides Java and Scala developers with access to HERE platform artifacts via Maven. It uses your HERE platform credentials to generate tokens so it can pull your Maven project dependencies from the HERE platform.

This way Marketplace and Workspace users may fetch platform schemas. In addition, Marketplace users may fetch the Java / Scala Data Client Library giving them access to data in the HERE Data API.

Go to the HERE Developer portal to learn more about the HERE platform.

To learn more about Maven Wagon visit this page.

System requirements

Version numbers higher than specified are more likely to work properly.

• Operating system:
  • Windows 10
  • MAC OSX 10
  • Linux (Ubuntu 16.04)
• Java 8
• Maven 3.6.3 or later

Prerequisites

To access libraries and schemas from the HERE platform, you need a HERE Workspace and/or a HERE Marketplace account. If you don’t have an account yet, go to Pricing and Plans to apply for a free trial.

Once you have enabled your account you need to create the credentials and prepare your environment. Workspace users can find corresponding guidance in the documentation for Java and Scala developers. Marketplace users can find instructions in the Marketplace Consumer user guide.

Please note, by default the Maven Wagon plugin uses the credentials.properties file provided in the .here directory in the user home directory. There are three options to override the credentials:

• The first option is the system property hereCredentialsFile, the property should be added to the maven command the following way -DhereCredentialsFile=/full/path/to/credentials.properties.
• The second option is the environment variable HERE_CREDENTIALS_FILE. The variable should contain the full file path to the credentials.properties file to be used. The variable is taken into account only if there is no system property provided.
• The third option is the environment variable HERE_CREDENTIALS_STRING, the variable should have the following format:

here.access.key.id=...
here.access.key.secret=...
here.client.id=...
here.user.id=...
here.token.endpoint.url=...

Note that providing credentials via HERE_CREDENTIALS_STRING variable have the lowest precedence

How to use it?

This Maven Wagon plugin is published on Maven Central so you can conveniently use it from your Maven POM.

For example, to fetch the HERE Map Content - Topology Geometry - Protocol Buffers schema and the related Java and Scala bindings set the following dependencies:

<dependencies>
  <dependency>
    <groupId>com.here.schema.rib</groupId>
    <artifactId>topology-geometry_v2_java</artifactId>
    <version>${topology-geometry.library.version}</version>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.here.schema.rib</groupId>
    <artifactId>topology-geometry_v2_proto</artifactId>
    <version>${topology-geometry.library.version}</version>
    <type>zip</type>
  </dependency>
  <dependency>
    <groupId>com.here.schema.rib</groupId>
    <artifactId>topology-geometry_v2_scala</artifactId>
    <version>${topology-geometry.library.version}</version>
    <type>jar</type>
  </dependency>
</dependencies>

<repositories>
  <!-- The reference to the HERE repository with schemas -->
  <repository>
    <id>HERE_PLATFORM_ARTIFACT</id>
    <layout>default</layout>
    <url>here+artifact-service://artifact-service</url>
  </repository>
</repositories>

<build>
  <extensions>
    <extension>
      <groupId>com.here.platform.artifact</groupId>
      <artifactId>artifact-wagon</artifactId>
      <version>${artifact.wagon.version}</version>
    </extension>
  </extensions>
</build>

As a Marketplace user you can add this dependency for fetching the Java / Scala Data Client Library:

<dependencies>
  <dependency>
    <groupId>com.here.platform.data.client</groupId>
    <artifactId>data-client_2.11</artifactId>
    <version>${data.client.library.version}</version>
  </dependency>
</dependencies>

<repositories>
  <!-- The reference to the HERE repository with schemas -->
  <repository>
    <id>HERE_PLATFORM_ARTIFACT</id>
    <layout>default</layout>
    <url>here+artifact-service://artifact-service</url>
  </repository>
</repositories>

<build>
  <extensions>
    <extension>
      <groupId>com.here.platform.artifact</groupId>
      <artifactId>artifact-wagon</artifactId>
      <version>${artifact.wagon.version}</version>
    </extension>
  </extensions>
</build>

here+artifact-service://artifact-service is placeholder URL which will be replaced by plugin dynamically based on your credentials. The latest versions of the Data Client Library and Schemas can be found in SDK documentation

Proxy Setup

To enable Maven and the HERE Maven Wagon Plugin to work behind a corporate proxy, you need to add the following proxy settings in the Maven settings file (settings.xml), which is normally located at ~/.m2/settings.xml:

<settings>
  <proxies>
    <proxy>
      <id>proxy1</id>
      <active>true</active>
      <protocol>https</protocol>
      <host>{enter your proxy host here}</host>
      <port>{enter your proxy port here}</port>
      <username>{enter your proxy username here}</username>
      <password>{enter your proxy password here}</password>
    </proxy>
    <proxy>
      <id>proxy2</id>
      <active>true</active>
      <protocol>here+https</protocol>
      <host>{enter your proxy host here}</host>
      <port>{enter your proxy port here}</port>
      <username>{enter your proxy username here}</username>
      <password>{enter your proxy password here}</password>
    </proxy>
    <proxy>
      <id>proxy3</id>
      <active>true</active>
      <protocol>here+artifact-service</protocol>
      <host>{enter your proxy host here}</host>
      <port>{enter your proxy port here}</port>
      <username>{enter your proxy username here}</username>
      <password>{enter your proxy password here}</password>
    </proxy>
  </proxies>
</settings>

License

Copyright (C) 2018-2024 HERE Europe B.V.

Unless otherwise noted in LICENSE files for specific files or directories, the LICENSE in the root applies to all content in this repository.

here-artifact-maven-wagon's Issues

Integrate maven-dependency-plugin

I would suggest to integrate the maven-dependency-plugin in CI and check that no warnings are emitted.

This is the output of an mvn org.apache.maven.plugins:maven-dependency-plugin:3.1.1:analyze-only command on the current repo:

[WARNING] Used undeclared dependencies found:
[WARNING]    org.codehaus.plexus:plexus-component-annotations:jar:1.7.1:provided
[WARNING]    org.apache.maven.resolver:maven-resolver-api:jar:1.1.1:provided
[WARNING]    org.apache.maven.resolver:maven-resolver-impl:jar:1.1.1:provided
[WARNING]    commons-io:commons-io:jar:2.5:compile
[WARNING]    com.fasterxml.jackson.core:jackson-annotations:jar:2.8.0:compile
[WARNING]    org.slf4j:slf4j-api:jar:1.7.24:compile
[WARNING]    org.apache.maven.resolver:maven-resolver-spi:jar:1.1.1:provided
[WARNING]    org.apache.maven:maven-artifact:jar:3.5.3:provided
[WARNING]    org.apache.maven.wagon:wagon-provider-api:jar:3.0.0:compile
[WARNING]    com.fasterxml.jackson.core:jackson-databind:jar:2.8.7:compile
[WARNING] Unused declared dependencies found:
[WARNING]    org.slf4j:jcl-over-slf4j:jar:1.7.24:compile
[WARNING]    org.slf4j:slf4j-simple:jar:1.7.24:compile
[WARNING]    org.codehaus.plexus:plexus-utils:jar:3.0.24:compile

I would suggest to also add the analyze-dep-mgt and the analyze-duplicate targets.

Integrate license-maven-plugin

I would suggest the use of the license-maven-plugin as part of the CI, in order to automatically check the current status and to prevent unlicensed files to unintentionally enter the codebase.

[WARNING] Could not transfer metadata XXX from/to HERE_PLATFORM_ARTIFACT

When I'm using this MAven artifact plugin I get a lot of warnings like:

[WARNING] Could not transfer metadata org.springframework.boot:spring-boot-starter-tomcat/maven-metadata.xml from/to HERE_PLATFORM_ARTIFACT (here+artifact-service://artifact-service): Cannot access here+artifact-service://artifact-service with type default using the available connector factories: BasicRepositoryConnectorFactory

Please make sure that this warnings are removed in future releases.

Artifacts that is not owned by HERE should and need to be ignored without any warning/error log. I prefer it to be silent.

Extension does not work with Maven 3.8.1

If my findings are correct Maven 3.8.1 does not work with com.here.platform.artifact:artifact-wagon:2.0.13
But it works with Maven 3.6.3 and IntelliJ