Migrate an Existing Schema Project
For projects created using schema archetype 0.6.4 or earlier: to publish and share your schema, you must update the schema project to the latest version by following these instructions:
-
Add the following sections to the pom.xml
located in your project's root directory:
-
project
node:
<distributionManagement>
<repository>
<id>HERE_PLATFORM_ARTIFACT</id>
<layout>default</layout>
<url>here+artifact-service://artifact-service</url>
</repository>
</distributionManagement>
<repositories>
<repository>
<id>HERE_PLATFORM_ARTIFACT</id>
<layout>default</layout>
<url>here+artifact-service://artifact-service</url>
</repository>
</repositories>
-
project > properties
node:
<protobuf.version>3.6.0</protobuf.version>
<here.plugin.version>2.1.10</here.plugin.version>
<artifact.wagon.version>2.0.10</artifact.wagon.version>
-
project > build
node:
<extensions>
<extension>
<groupId>com.here.platform.artifact</groupId>
<artifactId>artifact-wagon</artifactId>
<version>${artifact.wagon.version}</version>
</extension>
</extensions>
-
project > build > plugins
node:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.7</version>
<executions>
<execution>
<id>test-schema</id>
<phase>package</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<exportAntProperties>true</exportAntProperties>
<target>
<condition property="skipSchemaAttach" value="false" else="true">
<available file="${project.basedir}/schema.yml"/>
</condition>
</target>
</configuration>
</execution>
<execution>
<id>copy-schema</id>
<phase>package</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<skip>${skipSchemaAttach}</skip>
<target>
<echoproperties destfile="${project.build.directory}/build.properties"/>
<copy todir="${project.build.directory}" file="${project.basedir}/schema.yml" overwrite="true">
<filterset begintoken="${" endtoken="}" filtersfile="${project.build.directory}/build.properties"/>
</copy>
</target>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>1.6</version>
<configuration>
<skipAttach>${skipSchemaAttach}</skipAttach>
</configuration>
<executions>
<execution>
<id>attach-artifacts</id>
<phase>package</phase>
<goals>
<goal>attach-artifact</goal>
</goals>
<configuration>
<artifacts>
<artifact>
<file>${project.build.directory}/schema.yml</file>
<type>yml</type>
<classifier>here-schema</classifier>
</artifact>
</artifacts>
</configuration>
</execution>
</executions>
</plugin>
-
Update proto/pom.xml
as follows:
-
plugin > executions > execution > phase
element in layer-manifest-plugin
, proto-validate-plugin
, and maven-assembly-plugin
Maven plugin definitions from package to compile:
<phase>compile</phase>
-
project > build > plugins
node:
<plugin>
<artifactId>maven-jar-plugin</artifactId>
<executions>
<execution>
<id>default-jar</id>
<phase>package</phase>
<configuration>
<classifier>empty</classifier>
</configuration>
</execution>
</executions>
</plugin>
-
Update java/pom.xml
as follows:
-
plugin > version
element in the protoc-jar-maven-plugin
Maven plugin definition:
<version>3.6.0.1</version>
-
plugin > executions > execution > configuration > protocVersion
element in the protoc-jar-maven-plugin
Maven plugin definition:
<protocVersion>3.6.0</protocVersion>
-
Update scala_2.12/pom.xml
as follows:
-
plugin > executions > execution > configuration > protocVersion
element in the protoc-scala-maven-plugin
Maven plugin definition:
<protocVersion>3.6.0</protocVersion>
-
scalapb-runtime_2.12
definition in the dependencies > dependency
block:
<dependency>
<groupId>com.thesamet.scalapb</groupId>
<artifactId>scalapb-runtime_2.12</artifactId>
<version>0.8.0</version>
</dependency>
-
Create a schema marker file schema.yml
in the root folder of your schema project with the following content:
name: "${project.name}"
summary: "${project.description}"
layerSchema: true
Note that the project.name
and project.description
values are taken from the POM file. These values identify your schema on the platform. For more information, see the Publish a Schema Artifact chapter.
If the schema project contains only one schema, you need to create a schema.yml
file in the main directory on the same level as the POM file. If it is a multischema project, each with its own modules, then you need to create different schema.yml
files in the root of each module.
Upgrading schema plugins from v1.x.x to v2.x.x
HERE Maven plugins v2.1.10 include bug fixes that are not backwards compatible with schemas v1.x.x and earlier. Among the fixes is the possibility to structure the schema proto files in custom directories (including placing them directly into the proto > src > main > proto
directory) when Package Consistency
validator is disabled.
In order to use the latest HERE Maven plugins you must upgrade your schema project as per instructions below:
-
Update java/pom.xml
as follows:
-
plugin > executions > execution > configuration
element in the protoc-jar-maven-plugin
Maven plugin definition:
Replace content of inputDirectories
tag with the following configuration:
<inputDirectories>
<include>${project.build.directory}/proto</include>
</inputDirectories>
Replace content of includeDirectories
tag with the following configuration:
<includeDirectories>
<include>${project.build.directory}/proto</include>
<include>${project.build.directory}/proto-lib</include>
</includeDirectories>
-
Update scala_2.12/pom.xml
as follows:
-
plugin > executions > execution > configuration
element in the protoc-scala-maven-plugin
Maven plugin definition:
Replace content of inputDirectories
tag with the following configuration:
<inputDirectories>
<include>${project.build.directory}/proto</include>
</inputDirectories>
Replace content of includeDirectories
tag with the following configuration:
<includeDirectories>
<include>${project.build.directory}/proto-lib</include>
</includeDirectories>
-
Add the following configuration to assembly > fileSets
section in ds/src/assembly/proto.xml
:
<fileSet>
<directory>${project.build.directory}/proto-lib</directory>
<outputDirectory/>
</fileSet>
Skipping the above-mentioned updates may lead to build-time errors.
Adding scala 2.12 module to your schema project
In order to add the scala 2.12 module to your schema, you need to upgrade the HERE Maven plugins version in your project to v2.1.10 or later. For upgrade instructions from v1.x.x to v2.x.x, see the previous chapter.
Follow these steps to add the new scala_2.12 module to your project:
-
Create a new module in your schema:
- Create a
scala_2.12
directory in your root project folder. - Copy the scala 2.11 Maven module configuration from
scala/pom.xml
to scala_2.12/pom.xml
. -
Update the modules
section of the pom.xml
file in your root project directory to include the new module. Example:
<modules>
<module>proto</module>
<module>java</module>
<module>scala</module>
<module>scala_2.12</module>
<module>ds</module>
</modules>
-
Update scala_2.12/pom.xml
as follows:
- Rename
artifactId
from <schema-name>_scala_2.11
or <schema-name>_scala
to <schema-name>_scala_2.12
where <schema-name>
is the name of your schema. Please note that no changes should be made in scala/pom.xml
in order for your schema to be backwards compatible with the previous versions. - Update
name
and description
appropriately for the new module. -
Update the scala-library
version in dependencies
section to 2.12.x as shown in the example below:
<dependency>
<groupId>org.scala-lang</groupId>
<artifactId>scala-library</artifactId>
<version>2.12.12</version>
</dependency>
-
In the dependencies
section, replace the scalapb-runtime_2.11
dependency with the scalapb-runtime_2.12
one as follows:
<dependency>
<groupId>com.thesamet.scalapb</groupId>
<artifactId>scalapb-runtime_2.12</artifactId>
<version>0.8.0</version>
<exclusions>
<exclusion>
<groupId>org.scala-lang</groupId>
<artifactId>scala-library</artifactId>
</exclusion>
</exclusions>
</dependency>
-
In the build > plugins > protoc-scala-maven-plugin
plugin:
- Rename the
artifactId
of the protoc-scala-maven-plugin
to protoc-scala-maven-plugin_2.12
. -
Remove the dependencies section of the plugin if it exists. The final protoc-scala-maven-plugin_2.12
configuration may look like this:
<plugin>
<groupId>com.here.platform.schema.maven_plugins</groupId>
<artifactId>protoc-scala-maven-plugin_2.12</artifactId>
<version>${here.plugin.version}</version>
<executions>
<execution>
<phase>generate-sources</phase>
<goals>
<goal>scala-protoc-mojo</goal>
</goals>
<configuration>
<protocVersion>${protoc.version}</protocVersion>
<inputDirectories>
<include>${project.build.directory}/proto</include>
</inputDirectories>
<includeDirectories>
<include>${project.build.directory}/proto-lib</include>
</includeDirectories>
<includeStdTypes>true</includeStdTypes>
</configuration>
</execution>
</executions>
</plugin>
-
If your schema project contains Scala 2.11 and 2.12 modules, do not use the scala.version
or scala.compat.version
Maven properties. These variables may lead to runtime issues making either Scala 2.11 or 2.12 bindings unusable.
Note: Scala 2.11 bindings updates
Schemas created from project_archetype v1.0.0
and later get their Scala 2.11 bindings updated with scalapb v0.8.0
and may cause compilation errors in the project that uses them. The new bindings do not require you to use protobuf wrapper types like DoubleValue
. Please update your project code accordingly.
Remove scala 2.11 module from your schema project
As of 2.1.15
, the Schema Archetype Project does not support scala 2.11.
In order to remove scala 2.11 from the existing schema do the following:
- Increment schema version in the pom.xml files otherwise the scala 2.11 binding will not be deleted. Please note that the old version of the schema will contain scala 2.11 binding.
- Remove the
scala
module from the schema. - Remove the
<module>scala</module>
from the root pom.xml file - Redeploy the schema using the
mvn clean deploy
command.