[SPARK-53957][Geo][SQL] Support GEOGRAPHY and GEOMETRY in the SpatialReferenceSystemMapper

sql/api/src/main/scala/org/apache/spark/sql/internal/types/CartesianSpatialReferenceSystemMapper.java

@@ -0,0 +1,33 @@
+/*
+ * 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.internal.types;
+
+/**
+ * Class for providing SRS mappings for cartesian spatial reference systems.
+ */
+public class CartesianSpatialReferenceSystemMapper extends SpatialReferenceSystemMapper {
+  // Returns the string ID corresponding to the input SRID. If not supported, returns `null`.
+  public static String getStringId(int srid) {
+    return srsCache.isValidSrid(srid) ? srsCache.getSrsInfo(srid).stringId() : null;
+  }
+
+  // Returns the SRID corresponding to the input string ID. If not supported, returns `null`.
+  public static Integer getSrid(String stringId) {
+    return srsCache.isValidStringId(stringId) ? srsCache.getSrsInfo(stringId).srid() : null;
+  }
+}

sql/api/src/main/scala/org/apache/spark/sql/internal/types/GeographicSpatialReferenceSystemMapper.java

@@ -0,0 +1,33 @@
+/*
+ * 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.internal.types;
+
+/**
+ * Class for providing SRS mappings for geographic spatial reference systems.
+ */
+public class GeographicSpatialReferenceSystemMapper extends SpatialReferenceSystemMapper {
+  // Returns the string ID corresponding to the input SRID. If not supported, returns `null`.
+  public static String getStringId(int srid) {
+    return srsCache.isGeographicSrid(srid) ? srsCache.getSrsInfo(srid).stringId() : null;
+  }
+
+  // Returns the SRID corresponding to the input string ID. If not supported, returns `null`.
+  public static Integer getSrid(String stringId) {
+    return srsCache.isGeographicStringId(stringId) ? srsCache.getSrsInfo(stringId).srid() : null;
+  }
+}

sql/api/src/main/scala/org/apache/spark/sql/internal/types/SpatialReferenceSystemCache.java

@@ -0,0 +1,98 @@
+/*
+ * 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.internal.types;
+
+import org.apache.spark.sql.internal.util.SingletonBase;
+
+import java.util.HashMap;
+import java.util.List;
+
+/**
+ * Class for maintaining the mappings between supported SRID/CRS values and the corresponding SRS.
+ */
+public class SpatialReferenceSystemCache extends SingletonBase<SpatialReferenceSystemCache> {
+
+  // Private constructor to prevent external instantiation.
+  private SpatialReferenceSystemCache() {
+    populateSpatialReferenceSystemInformationMapping();
+  }
+
+  @Override
+  protected SpatialReferenceSystemCache createInstance() {
+    return new SpatialReferenceSystemCache();
+  }
+
+  public static SpatialReferenceSystemCache getInstance() {
+    return SingletonBase.getInstance(new SpatialReferenceSystemCache());
+  }
+
+  // Hash map for defining the mappings from the integer SRID value to the full SRS information.
+  private final HashMap<Integer, SpatialReferenceSystemInformation> sridToSrs =
+      new HashMap<>();
+
+  // Hash map for defining the mappings from the string ID value to the full SRS information.
+  private final HashMap<String, SpatialReferenceSystemInformation> stringIdToSrs =
+      new HashMap<>();
+
+  // Helper method for building the SRID-to-SRS and stringID-to-SRS mappings.
+  private void populateSpatialReferenceSystemInformationMapping() {
+    // Currently, we only support a limited set of SRID / CRS values. However, we will soon extend
+    // this to support all the SRIDs supported by relevant authorities and libraries. The SRS list
+    // below will be updated accordingly, and the maps will be populated with more complete data.
+    List<SpatialReferenceSystemInformation> srsInformationList = List.of(
+      new SpatialReferenceSystemInformation(0, "SRID:0", false),
+      new SpatialReferenceSystemInformation(3857, "EPSG:3857", false),
+      new SpatialReferenceSystemInformation(4326, "OGC:CRS84", true)
+    );
+    // Populate the mappings using the same SRS information objects, avoiding any duplication.
+    for (SpatialReferenceSystemInformation srsInformation: srsInformationList) {
+      sridToSrs.put(srsInformation.srid(), srsInformation);
+      stringIdToSrs.put(srsInformation.stringId(), srsInformation);
+    }
+  }
+
+  // Utility method that can be used to check whether an SRID value is valid or not.
+  public boolean isValidSrid(int srid) {
+    return sridToSrs.containsKey(srid);
+  }
+
+  // Utility method that can be used to check whether an SRID value is geographic or not.
+  public boolean isGeographicSrid(int srid) {
+    return isValidSrid(srid) && sridToSrs.get(srid).isGeographic();
+  }
+
+  // Utility method that can be used to check whether a string ID value is valid or not.
+  public boolean isValidStringId(String stringId) {
+    return stringIdToSrs.containsKey(stringId);
+  }
+
+  // Utility method that can be used to check whether a string ID value is geographic or not.
+  public boolean isGeographicStringId(String stringId) {
+    return isValidStringId(stringId) && stringIdToSrs.get(stringId).isGeographic();
+  }
+
+  // Returns the SRS corresponding to the input SRID. If not supported, returns `null`.
+  public SpatialReferenceSystemInformation getSrsInfo(int srid) {
+    return sridToSrs.getOrDefault(srid, null);
+  }
+
+  // Returns the SRS corresponding to the input string ID. If not supported, returns `null`.
+  public SpatialReferenceSystemInformation getSrsInfo(String stringId) {
+    return stringIdToSrs.getOrDefault(stringId, null);
+  }
+}

sql/api/src/main/scala/org/apache/spark/sql/internal/types/SpatialReferenceSystemInformation.java

@@ -0,0 +1,55 @@
+/*
+ * 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.internal.types;
+
+/**
+ * Class for maintaining information about a spatial reference system (SRS).
+ */
+public class SpatialReferenceSystemInformation {
+
+  // Field storing the spatial reference identifier (SRID) value of this SRS.
+  private final int srid;
+
+  // Field storing the string ID of the corresponding coordinate reference system (CRS).
+  private final String stringId;
+
+  // Field indicating whether the spatial reference system (SRS) is geographic or not.
+  private final boolean isGeographic;
+
+  // Constructor for creating an instance of the spatial reference system information class.
+  public SpatialReferenceSystemInformation(int srid, String stringId, boolean isGeographic) {
+    this.srid = srid;
+    this.stringId = stringId;
+    this.isGeographic = isGeographic;
+  }
+
+  // Specialized getters for each of the spatial reference system (SRS) information fields.
+
+  public int srid() {
+      return srid;
+  }
+
+  public String stringId() {
+      return stringId;
+  }
+
+  public boolean isGeographic() {
+      return isGeographic;
+  }
+
+}

sql/api/src/main/scala/org/apache/spark/sql/internal/types/SpatialReferenceSystemMapper.java

@@ -17,59 +17,10 @@
 
 package org.apache.spark.sql.internal.types;
 
-import java.util.HashMap;
-
-/*
- * Class for maintaining mappings between supported SRID values and the string ID of the
- * corresponding CRS.
+/**
+ * Abstract class for providing SRS mappings for spatial reference systems.
  */
-public class SpatialReferenceSystemMapper {
-
-  // We implement this class as a singleton (we disallow construction).
-  private SpatialReferenceSystemMapper() {}
-
-  private static final SpatialReferenceSystemMapper Instance = new SpatialReferenceSystemMapper();
-
-  // Returns the unique instance of this class.
-  public static SpatialReferenceSystemMapper get() {
-    return Instance;
-  }
-
-  // Hash maps defining the mappings to/from SRID and string ID for a CRS.
-  private static final HashMap<Integer, String> sridToStringId = buildSridToStringIdMap();
-  private static final HashMap<String, Integer> stringIdToSrid = buildStringIdToSridMap();
-
-  // Returns the string ID corresponding to the input SRID. If the input SRID is not supported,
-  // `null` is returned.
-  public String getStringId(int srid) {
-    return sridToStringId.get(srid);
-  }
-
-  // Returns the SRID corresponding to the input string ID. If the input string ID is not
-  // supported, `null` is returned.
-  public Integer getSrid(String stringId) {
-    return stringIdToSrid.get(stringId);
-  }
-
-  // Currently, we only support a limited set of SRID / CRS mappings. However, we will soon extend
-  // this to support all the SRIDs supported by relevant authorities and libraries. The methods
-  // below will be updated accordingly, in order to populate the mappings with more complete data.
-
-  // Helper method for building the SRID-to-string-ID mapping.
-  private static HashMap<Integer, String> buildSridToStringIdMap() {
-    HashMap<Integer, String> map = new HashMap<>();
-    map.put(0, "SRID:0"); // Unspecified
-    map.put(3857, "EPSG:3857"); // Web Mercator
-    map.put(4326, "OGC:CRS84"); // WGS84
-    return map;
-  }
-
-  // Helper method for building the string-ID-to-SRID mapping.
-  private static HashMap<String, Integer> buildStringIdToSridMap() {
-    HashMap<String, Integer> map = new HashMap<>();
-    map.put("SRID:0", 0); // Unspecified
-    map.put("EPSG:3857", 3857); // Web Mercator
-    map.put("OGC:CRS84", 4326); // WGS84
-    return map;
-  }
+public abstract class SpatialReferenceSystemMapper {
+  protected static final SpatialReferenceSystemCache srsCache =
+      SpatialReferenceSystemCache.getInstance();
 }

sql/api/src/main/scala/org/apache/spark/sql/internal/util/SingletonBase.java

@@ -0,0 +1,46 @@
+/*
+ * 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.internal.util;
+
+/**
+ * Generic abstract base class for implementing the singleton design pattern. This class is lazily
+ * initialized, thread-safe, and generic (it can be used to create singletons for any type `T`).
+ */
+public abstract class SingletonBase<T> {
+  // The singleton `instance` is created lazily, meaning that it is not instantiated until the
+  // `getInstance()` method is called for the first time. Note that this solution is thread-safe.
+  private static volatile Object instance = null;
+
+  // The `createInstance` method is abstract, so all subclasses must implement it. Note that
+  // this method defines how the singleton instance is created for the specific subclass.
+  protected abstract T createInstance();
+
+  // The `getInstance` method uses double-checked locking to ensure efficient and safe instance
+  // creation. The singleton instance is created only once, even in a multithreaded environment.
+  @SuppressWarnings("unchecked")
+  public static <T> T getInstance(SingletonBase<T> singletonBase) {
+    if (instance == null) {
+      synchronized (SingletonBase.class) {
+        if (instance == null) {
+          instance = singletonBase.createInstance();
+        }
+      }
+    }
+    return (T) instance;
+  }
+}