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

[gi...@apache.org]

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

github-bot pushed a commit to branch site
in repository https://gitbox.apache.org/repos/asf/calcite.git


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

commit 56c902cc91131761cafe44687f633ad7b1c04657
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 dc671be395..ce8e3e9d27 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 cbc3662d4f..86f4819d20 100644
--- a/site/_docs/reference.md
+++ b/site/_docs/reference.md
@@ -2420,6 +2420,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