[calcite] branch main updated: [CALCITE-5399] Remove Proj4J from the api dependencies

[bc...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

bchapuis pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/calcite.git


The following commit(s) were added to refs/heads/main by this push:
     new 687dec0afc [CALCITE-5399] Remove Proj4J from the api dependencies
687dec0afc is described below

commit 687dec0afcfab781f905b16e422bc03bd6b9209e
Author: Bertil Chapuis <bc...@gmail.com>
AuthorDate: Mon Nov 28 22:08:16 2022 +0100

    [CALCITE-5399] Remove Proj4J from the api dependencies
---
 core/build.gradle.kts                                            | 6 +++++-
 .../java/org/apache/calcite/runtime/ProjectionTransformer.java   | 8 ++++++++
 site/_docs/howto.md                                              | 2 ++
 site/_docs/reference.md                                          | 7 +++++++
 site/_docs/spatial.md                                            | 9 +++++++++
 5 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/core/build.gradle.kts b/core/build.gradle.kts
index 3bafb99464..2a5a6eb365 100644
--- a/core/build.gradle.kts
+++ b/core/build.gradle.kts
@@ -48,7 +48,11 @@ dependencies {
 
     api("org.locationtech.jts:jts-core")
     api("org.locationtech.jts.io:jts-io-common")
-    api("org.locationtech.proj4j:proj4j")
+
+    // Due to restricting terms of use, we cannot include Proj4J as an API dependency.
+    compileOnly("org.locationtech.proj4j:proj4j")
+    testRuntimeOnly("org.locationtech.proj4j:proj4j")
+
     api("com.fasterxml.jackson.core:jackson-annotations")
     api("com.google.errorprone:error_prone_annotations")
     api("com.google.guava:guava")
diff --git a/core/src/main/java/org/apache/calcite/runtime/ProjectionTransformer.java b/core/src/main/java/org/apache/calcite/runtime/ProjectionTransformer.java
index 825d5e7de1..f199ebeb50 100644
--- a/core/src/main/java/org/apache/calcite/runtime/ProjectionTransformer.java
+++ b/core/src/main/java/org/apache/calcite/runtime/ProjectionTransformer.java
@@ -40,6 +40,14 @@ import java.util.stream.Stream;
 
 /**
  * Transforms the projection of a geometry.
+ *
+ * This class uses Proj4J to transform the projection of a geometry
+ * and should not be used beyond the scope of the Spatial Type Extensions.
+ * Proj4J is released under the Apache License 2.0, however, it also uses the EPSG dataset,
+ * which has restricting <a href="https://epsg.org/terms-of-use.html">terms of use</a>.
+ * As a result, Proj4J is not suitable for inclusion in Apache Calcite
+ * and this class will throw {@code ClassNotFoundException}s
+ * if Proj4J is not added to the classpath by the user.
  */
 public class ProjectionTransformer extends GeometryTransformer {
 
diff --git a/site/_docs/howto.md b/site/_docs/howto.md
index 921a962ce9..a3833997a1 100644
--- a/site/_docs/howto.md
+++ b/site/_docs/howto.md
@@ -841,6 +841,8 @@ your key to the keyservers used by Nexus, see above.
   that the `META-INF` directory contains `LICENSE`,
   `NOTICE`
 * Check PGP, per [this](https://httpd.apache.org/dev/verification.html)
+* Check that Proj4J is not among the api and implementation dependencies,
+  as the EPSG database is not redistributable.
 
 Verify the staged artifacts in the Nexus repository:
 
diff --git a/site/_docs/reference.md b/site/_docs/reference.md
index 7dd8172c6f..a0c759d370 100644
--- a/site/_docs/reference.md
+++ b/site/_docs/reference.md
@@ -2432,6 +2432,13 @@ Not implemented:
 
 #### Geometry projection functions
 
+Projection functions rely on Proj4J to transform the geometries.
+Proj4J is released under the Apache License 2.0, however, it also uses the EPSG dataset,
+which has restricting [terms of use](https://epsg.org/terms-of-use.html).
+As a result, Proj4J is not suitable for inclusion in Apache Calcite
+and some of these functions may throw `ClassNotFoundException`s.
+Users can still use these functions by including Proj4J in their classpath.
+
 | C | Operator syntax      | Description
 |:- |:-------------------- |:-----------
 | o | ST_SetSRID(geom, srid) | Returns a copy of *geom* with a new SRID
diff --git a/site/_docs/spatial.md b/site/_docs/spatial.md
index d0b2ec85d4..2fe588e789 100644
--- a/site/_docs/spatial.md
+++ b/site/_docs/spatial.md
@@ -148,6 +148,15 @@ These rewrites are worth performing because they are much quicker to apply,
 and often allow range scans on the Hilbert index.
 But for safety, Calcite applies the original predicate, to remove false positives.
 
+## Limitations
+
+Some spatial functions rely on Proj4J to transform the projection of spatial objects.
+Proj4J is released under the Apache License 2.0, however, it also uses the EPSG dataset,
+which has restricting [terms of use](https://epsg.org/terms-of-use.html).
+As a result, Proj4J is not suitable for inclusion in Apache Calcite
+and these functions will throw `ClassNotFoundException`s.
+Users can still use these functions by including Proj4J in their classpath.
+
 ## Acknowledgements
 
 Calcite's OpenGIS implementation uses the