[SPARK-54033][Geo][SQL] Introduce Catalyst server-side geospatial execution classes

sql/catalyst/src/main/java/org/apache/spark/sql/catalyst/util/Geo.java

@@ -0,0 +1,43 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.spark.sql.catalyst.util;
+
+// Helper interface for the APIs expected from top-level GEOMETRY and GEOGRAPHY classes.
+interface Geo {
+
+  /** Binary converters. */
+
+  // Returns the Well-Known Binary (WKB) representation of the geo object.
+  byte[] toWkb();
+
+  // Returns the Extended Well-Known Binary (EWKB) representation of the geo object.
+  byte[] toEwkb();
+
+  /** Textual converters. */
+
+  // Returns the Well-Known Text (WKT) representation of the geo object.
+  byte[] toWkt();
+
+  // Returns the Extended Well-Known Text (EWKT) representation of the geo object.
+  byte[] toEwkt();
+
+  /** Other methods. */
+
+  // Returns the Spatial Reference Identifier (SRID) value of the geo object.
+  int srid();
+
+}

sql/catalyst/src/main/java/org/apache/spark/sql/catalyst/util/Geography.java

@@ -0,0 +1,147 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.spark.sql.catalyst.util;
+
+import org.apache.spark.unsafe.types.GeographyVal;
+
+import java.util.Arrays;
+
+// Catalyst-internal server-side execution wrapper for GEOGRAPHY.
+public final class Geography implements Geo {
+
+  /** Geography internal implementation. */
+
+  // The Geography type is implemented as an array of bytes stored inside a `GeographyVal` object.
+  protected final GeographyVal value;
+
+  /** Geography constants. */
+
+  // The default SRID value for GEOGRAPHY values.
+  public static int DEFAULT_SRID = 4326;
+
+  /** Geography constructors and factory methods. */
+
+  // We make the constructors private. Use `fromBytes` or `fromValue` to create new instances.
+  private Geography(byte[] bytes) {
+    this.value = GeographyVal.fromBytes(bytes);
+  }
+
+  private Geography(GeographyVal value) {
+    this.value = value;
+  }
+
+  // Factory methods to create new Geography instances from a byte array or a `GeographyVal`.
+  public static Geography fromBytes(byte[] bytes) {
+    return new Geography(bytes);
+  }
+
+  public static Geography fromValue(GeographyVal value) {
+    return new Geography(value);
+  }
+
+  /** Geography getters and instance methods. */
+
+  // Returns the underlying physical type value of this Geography instance.
+  public GeographyVal getValue() {
+    return value;
+  }
+
+  // Returns the byte array containing the GEOGRAPHY representation/encoding.
+  public byte[] getBytes() {
+    return value.getBytes();
+  }
+
+  // Returns a copy of this geography.
+  public Geography copy() {
+    byte[] bytes = getBytes();
+    return Geography.fromBytes(Arrays.copyOf(bytes, bytes.length));
+  }
+
+  /** Geography WKB parsing. */
+
+  // Returns a Geography object with the specified SRID value by parsing the input WKB.
+  public static Geography fromWkb(byte[] wkb, int srid) {
+    throw new UnsupportedOperationException("Geography WKB parsing is not yet supported.");
+  }
+
+  // Overload for the WKB reader where we use the default SRID for Geography.
+  public static Geography fromWkb(byte[] wkb) {
+    return fromWkb(wkb, DEFAULT_SRID);
+  }
+
+  /** Geography EWKB parsing. */
+
+  // Returns a Geography object by parsing the input EWKB.
+  public static Geography fromEwkb(byte[] ewkb) {
+    throw new UnsupportedOperationException("Geography EWKB parsing is not yet supported.");
+  }
+
+  /** Geography WKT parsing. */
+
+  // Returns a Geography object with the specified SRID value by parsing the input WKT.
+  public static Geography fromWkt(byte[] wkt, int srid) {
+    throw new UnsupportedOperationException("Geography WKT parsing is not yet supported.");
+  }
+
+  // Overload for the WKT reader where we use the default SRID for Geography.
+  public static Geography fromWkt(byte[] wkt) {
+    return fromWkt(wkt, DEFAULT_SRID);
+  }
+
+  /** Geography EWKT parsing. */
+
+  // Returns a Geography object by parsing the input EWKT.
+  public static Geography fromEwkt(byte[] ewkt) {
+    throw new UnsupportedOperationException("Geography EWKT parsing is not yet supported.");
+  }
+
+  /** Geography binary standard format converters: WKB and EWKB. */
+
+  @Override
+  public byte[] toWkb() {
+    // Once WKB conversion is implemented, it should support NDR and XDR endianness.
+    throw new UnsupportedOperationException("Geography WKB conversion is not yet supported.");
+  }
+
+  @Override
+  public byte[] toEwkb() {
+    // Once EWKB conversion is implemented, it should support NDR and XDR endianness.
+    throw new UnsupportedOperationException("Geography EWKB conversion is not yet supported.");
+  }
+
+  /** Geography textual standard format converters: WKT and EWKT. */
+
+  @Override
+  public byte[] toWkt() {
+    // Once WKT conversion is implemented, it should support various precisions.
+    throw new UnsupportedOperationException("Geography WKT conversion is not yet supported.");
+  }
+
+  @Override
+  public byte[] toEwkt() {
+    // Once EWKT conversion is implemented, it should support various precisions.
+    throw new UnsupportedOperationException("Geography EWKT conversion is not yet supported.");
+  }
+
+  /** Other instance methods, inherited from the `Geo` interface. */
+
+  @Override
+  public int srid() {
+    throw new UnsupportedOperationException("Geography SRID is not yet supported.");
+  }
+
+}

sql/catalyst/src/main/java/org/apache/spark/sql/catalyst/util/Geometry.java

@@ -0,0 +1,147 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.spark.sql.catalyst.util;
+
+import org.apache.spark.unsafe.types.GeometryVal;
+
+import java.util.Arrays;
+
+// Catalyst-internal server-side execution wrapper for GEOMETRY.
+public final class Geometry implements Geo {
+
+  /** Geometry internal implementation. */
+
+  // The Geometry type is implemented as an array of bytes stored inside a `GeometryVal` object.
+  protected final GeometryVal value;
+
+  /** Geometry constants. */
+
+  // The default SRID value for GEOMETRY values.
+  public static int DEFAULT_SRID = 0;
+
+  /** Geometry constructors and factory methods. */
+
+  // We make the constructors private. Use `fromBytes` or `fromValue` to create new instances.
+  private Geometry(byte[] bytes) {
+    this.value = GeometryVal.fromBytes(bytes);
+  }
+
+  private Geometry(GeometryVal value) {
+    this.value = value;
+  }
+
+  // Factory methods to create new Geometry instances from a byte array or a `GeometryVal`.
+  public static Geometry fromBytes(byte[] bytes) {
+    return new Geometry(bytes);
+  }
+
+  public static Geometry fromValue(GeometryVal value) {
+    return new Geometry(value);
+  }
+
+  /** Geometry getters and instance methods. */
+
+  // Returns the underlying physical type value of this Geometry instance.
+  public GeometryVal getValue() {
+    return value;
+  }
+
+  // Returns the byte array containing the GEOMETRY representation/encoding.
+  public byte[] getBytes() {
+    return value.getBytes();
+  }
+
+  // Returns a copy of this geometry.
+  public Geometry copy() {
+    byte[] bytes = getBytes();
+    return Geometry.fromBytes(Arrays.copyOf(bytes, bytes.length));
+  }
+
+  /** Geometry WKB parsing. */
+
+  // Returns a Geometry object with the specified SRID value by parsing the input WKB.
+  public static Geometry fromWkb(byte[] wkb, int srid) {
+    throw new UnsupportedOperationException("Geometry WKB parsing is not yet supported.");
+  }
+
+  // Overload for the WKB reader where we use the default SRID for Geometry.
+  public static Geometry fromWkb(byte[] wkb) {
+    return fromWkb(wkb, DEFAULT_SRID);
+  }
+
+  /** Geometry EWKB parsing. */
+
+  // Returns a Geometry object by parsing the input EWKB.
+  public static Geometry fromEwkb(byte[] ewkb) {
+    throw new UnsupportedOperationException("Geometry EWKB parsing is not yet supported.");
+  }
+
+  /** Geometry WKT parsing. */
+
+  // Returns a Geometry object with the specified SRID value by parsing the input WKT.
+  public static Geometry fromWkt(byte[] wkt, int srid) {
+    throw new UnsupportedOperationException("Geometry WKT parsing is not yet supported.");
+  }
+
+  // Overload for the WKT reader where we use the default SRID for Geometry.
+  public static Geometry fromWkt(byte[] wkt) {
+    return fromWkt(wkt, DEFAULT_SRID);
+  }
+
+  /** Geometry EWKT parsing. */
+
+  // Returns a Geometry object by parsing the input EWKT.
+  public static Geometry fromEwkt(byte[] ewkt) {
+    throw new UnsupportedOperationException("Geometry EWKT parsing is not yet supported.");
+  }
+
+  /** Geometry binary standard format converters: WKB and EWKB. */
+
+  @Override
+  public byte[] toWkb() {
+    // Once WKB conversion is implemented, it should support NDR and XDR endianness.
+    throw new UnsupportedOperationException("Geometry WKB conversion is not yet supported.");
+  }
+
+  @Override
+  public byte[] toEwkb() {
+    // Once EWKB conversion is implemented, it should support NDR and XDR endianness.
+    throw new UnsupportedOperationException("Geometry EWKB conversion is not yet supported.");
+  }
+
+  /** Geometry textual standard format converters: WKT and EWKT. */
+
+  @Override
+  public byte[] toWkt() {
+    // Once WKT conversion is implemented, it should support various precisions.
+    throw new UnsupportedOperationException("Geometry WKT conversion is not yet supported.");
+  }
+
+  @Override
+  public byte[] toEwkt() {
+    // Once EWKT conversion is implemented, it should support various precisions.
+    throw new UnsupportedOperationException("Geometry EWKT conversion is not yet supported.");
+  }
+
+  /** Other instance methods, inherited from the `Geo` interface. */
+
+  @Override
+  public int srid() {
+    throw new UnsupportedOperationException("Geometry SRID is not yet supported.");
+  }
+
+}