Expand spatial types supported by NewtonsoftJsonMicrosoftSpatialGeoJsonConverter. (Azure#24587)

* Added support for LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon, and Collection. Code structure mirrors MicrosoftSpatialGeoJsonConverter.

* Reworded and slightly restructured comments. Renamed variable.

Author: Jack Bond

sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/src/GeoJsonConstants.cs

@@ -0,0 +1,23 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Azure.Core.Serialization
+{
+    /// <summary>
+    /// The constants defined by the GeoJson standard
+    /// A similar class exists in Microsoft.Spatial, unfortunately it is marked as internal.
+    /// </summary>
+    internal static class GeoJsonConstants
+    {
+        public const string PointTypeName = "Point";
+        public const string LineStringTypeName = "LineString";
+        public const string PolygonTypeName = "Polygon";
+        public const string MultiPointTypeName = "MultiPoint";
+        public const string MultiLineStringTypeName = "MultiLineString";
+        public const string MultiPolygonTypeName = "MultiPolygon";
+        public const string GeometryCollectionTypeName = "GeometryCollection";
+        public const string CoordinatesPropertyName = "coordinates";
+        public const string TypePropertyName = "type";
+        public const string GeometriesPropertyName = "geometries";
+    }
+}

sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/src/GeoJsonCoordinateReader.cs

@@ -0,0 +1,105 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using Microsoft.Spatial;
+using Newtonsoft.Json;
+
+namespace Azure.Core.Serialization
+{
+    /// <summary>
+    /// Advances a JsonReader positioned at coordinates property to identify GeoJson type.
+    /// </summary>
+    /// <remarks>
+    /// The GeoJson standard essentially has four "schemas" for containing geography coordinates.
+    /// <list type="bullet" >
+    /// <item>
+    /// <description>Level zero defines a Point an array of doubles for latitude, longitude, etc.</description>
+    /// </item>
+    /// <item>
+    /// <description>
+    /// Level one, defines a LineString or MultiPoint, both which are an array of points.
+    /// </description>
+    /// </item>
+    /// <item>
+    /// <description>
+    /// Level two, defines a Polygon or MultiLineString, an array of an array of points.
+    /// </description>
+    /// </item>
+    /// <item>
+    /// <description>
+    /// Level three, defines a MultiPolygon, an array of an array of an array of points.
+    /// </description>
+    /// </item>
+    /// </list>
+    /// </remarks>
+    internal abstract class GeoJsonCoordinateReader
+    {
+        /// <summary>
+        /// Advances the JsonReader and extracts the points which compose a Geography.
+        /// </summary>
+        /// <param name="reader"></param>
+        public abstract void Process(JsonReader reader);
+
+        /// <summary>
+        /// Accepts the GeoJson coordinates property, and iterates the top level array to determine
+        /// which of the four schemas the coordinates match.
+        /// </summary>
+        /// <param name="reader">A JsonReader positioned at the GeoJson coordinates property.</param>
+        /// <returns>A reader which will parse out correct parser based on the schema detected.</returns>
+        /// <exception cref="JsonSerializationException"></exception>
+        public static GeoJsonCoordinateReader Create(JsonReader reader)
+        {
+            GeoJsonCoordinateReader result;
+
+            reader.Expect(JsonToken.StartArray);
+
+            int detectedLevel = 0;
+
+            // How many nested StartArray tokens we find identifies which of the four schemas we're dealing with
+            for (; reader.Read() && reader.TokenType == JsonToken.StartArray; detectedLevel++)
+            {
+                if (detectedLevel == 4)
+                {
+                    throw new JsonSerializationException($"Deserialization failed: GeoJson property '{GeoJsonConstants.CoordinatesPropertyName}' does not contain recognizable GeoJson.");
+                }
+            }
+
+            reader.ExpectNumber();
+
+            switch (detectedLevel)
+            {
+                case 0:
+                    result = new LevelZeroGeoJsonCoordinateReader();
+                    break;
+
+                case 1:
+                    result = new LevelOneGeoJsonCoordinateReader();
+                    break;
+
+                case 2:
+                    result = new LevelTwoGeoJsonCoordinateReader();
+                    break;
+
+                default:
+                    result = new LevelThreeGeoJsonCoordinateReader();
+                    break;
+            }
+
+            result.Process(reader);
+
+            return result;
+        }
+
+        /// <summary>
+        /// Returns a Geography created with the set of points extracted during the call to Process.
+        /// </summary>
+        /// <remarks>
+        /// GetGeography will be called only after both the type and coordinates GeoJson properties have
+        /// been read. As both LineString and MultiPoint share the same schema, a reader cannot know which
+        /// type to create from the points alone. The same is true for Polygon and MultiLineString.
+        /// </remarks>
+        /// <param name="type">The type read from the GeoJson type property.</param>
+        /// <returns>The Geography created by a level zero, one, two, or three reader.</returns>
+        public abstract Geography GetGeography(string type);
+    }
+}

sdk/core/Microsoft.Azure.Core.Spatial.NewtonsoftJson/src/GeographyFactoryExtensions.cs

@@ -0,0 +1,250 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using Microsoft.Spatial;
+using Newtonsoft.Json;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace Azure.Core.Serialization
+{
+    /// <summary>
+    /// A collection of extension methods for GeographyFactory.
+    /// </summary>
+    /// <remarks>
+    /// GeographyFactory does not contain overloads for adding existing Geographies during the Build process. For example,
+    /// you cannot simply add a GeographyPolygon to a GeographyMultiPolygon. Instead you must enumerate an existing
+    /// GeographyPolygon's rings and add them iteratively while creating a GeographyMultiPolygon. The methods of this
+    /// class properly iterate creating Geographies which are composed of other Geographies.
+    /// </remarks>
+    internal static class GeographyFactoryExtensions
+    {
+        public static GeographyFactory<GeographyCollection> Add(this GeographyFactory<GeographyCollection> factory, Geography geography)
+        {
+            if (geography is GeographyPoint point)
+            {
+                factory = factory.Add(point);
+            }
+
+            else if (geography is GeographyLineString lineString)
+            {
+                factory = factory.Add(lineString);
+            }
+
+            else if (geography is GeographyPolygon polygon)
+            {
+                factory = factory.Add(polygon);
+            }
+
+            else if (geography is GeographyMultiPoint multiPoint)
+            {
+                factory = factory.Add(multiPoint);
+            }
+
+            else if (geography is GeographyMultiLineString multiLineString)
+            {
+                factory = factory.Add(multiLineString);
+            }
+
+            else if (geography is GeographyMultiPolygon multiPolygon)
+            {
+                factory = factory.Add(multiPolygon);
+            }
+
+            else if (geography is GeographyCollection geographyCollection)
+            {
+                factory = factory.Add(geographyCollection);
+            }
+
+            return factory;
+        }
+
+        private static GeographyFactory<GeographyCollection> Add(this GeographyFactory<GeographyCollection> factory, GeographyPoint point)
+        {
+            factory = factory.Point(point.Latitude, point.Longitude);
+
+            return factory;
+        }
+
+        private static GeographyFactory<GeographyCollection> Add(this GeographyFactory<GeographyCollection> factory, GeographyLineString lineString)
+        {
+            factory = factory.LineString();
+
+            foreach (GeographyPoint point in lineString.Points)
+            {
+                factory = factory.LineTo(point.Latitude, point.Longitude);
+            }
+
+            return factory;
+        }
+
+        private static GeographyFactory<GeographyCollection> Add(this GeographyFactory<GeographyCollection> factory, GeographyPolygon polygon)
+        {
+            factory = factory.Polygon();
+
+            foreach (GeographyLineString ring in polygon.Rings)
+            {
+                factory = factory.Ring(ring.Points[0].Latitude, ring.Points[0].Longitude);
+
+                for (int i = 1; i < ring.Points.Count; i++)
+                {
+                    factory = factory.LineTo(ring.Points[i].Latitude, ring.Points[i].Longitude);
+                }
+            }
+
+            return factory;
+        }
+
+        private static GeographyFactory<GeographyCollection> Add(this GeographyFactory<GeographyCollection> factory, GeographyMultiPoint multiPoint)
+        {
+            foreach (GeographyPoint point in multiPoint.Points)
+            {
+                factory = factory.Add(point);
+            }
+
+            return factory;
+        }
+
+        private static GeographyFactory<GeographyCollection> Add(this GeographyFactory<GeographyCollection> factory, GeographyMultiLineString multiLineString)
+        {
+            foreach (GeographyLineString lineString in multiLineString.LineStrings)
+            {
+                factory = factory.Add(lineString);
+            }
+
+            return factory;
+        }
+
+        private static GeographyFactory<GeographyCollection> Add(this GeographyFactory<GeographyCollection> factory, GeographyMultiPolygon multiPolygon)
+        {
+            foreach (GeographyPolygon polygon in multiPolygon.Polygons)
+            {
+                factory = factory.Add(polygon);
+            }
+
+            return factory;
+        }
+
+        private static GeographyFactory<GeographyCollection> Add(this GeographyFactory<GeographyCollection> factory, GeographyCollection geographyCollection)
+        {
+            factory = factory.Collection();
+
+            foreach (Geography geography in geographyCollection.Geographies)
+            {
+                factory = factory.Add(geography);
+            }
+
+            return factory;
+        }
+
+        public static GeographyLineString Create(this GeographyFactory<GeographyLineString> factory, List<GeographyPoint> points)
+        {
+            if (points.Count < 2)
+            {
+                throw new JsonSerializationException($"Deserialization failed: GeoJson type '{GeoJsonConstants.LineStringTypeName}' must contain at least two points.");
+            }
+
+            foreach (GeographyPoint point in points)
+            {
+                factory = factory.LineTo(point.Latitude, point.Longitude);
+            }
+
+            GeographyLineString result = factory.Build();
+
+            return result;
+        }
+
+        public static GeographyPolygon Create(this GeographyFactory<GeographyPolygon> factory, List<List<GeographyPoint>> points)
+        {
+            foreach (List<GeographyPoint> pointList in points)
+            {
+                if (pointList.Count < 4)
+                {
+                    throw new JsonSerializationException($"Deserialization failed: GeoJson type '{GeoJsonConstants.PolygonTypeName}' must contain at least four points.");
+                }
+
+                else if (!pointList.First().Equals(pointList.Last()))
+                {
+                    throw new JsonSerializationException($"Deserialization failed: GeoJson type '{GeoJsonConstants.PolygonTypeName}' has an invalid ring, its first and last points do not match.");
+                }
+
+                factory = factory.Ring(pointList[0].Latitude, pointList[0].Longitude);
+
+                for (int i = 1; i < pointList.Count - 1; i++)
+                {
+                    factory = factory.LineTo(pointList[i].Latitude, pointList[i].Longitude);
+                }
+            }
+
+            var result = factory.Build();
+
+            return result;
+        }
+
+        public static GeographyMultiPoint Create(this GeographyFactory<GeographyMultiPoint> factory, List<GeographyPoint> points)
+        {
+            foreach (GeographyPoint point in points)
+            {
+                factory = factory.Point(point.Latitude, point.Longitude);
+            }
+
+            GeographyMultiPoint result = factory.Build();
+
+            return result;
+        }
+
+        public static GeographyMultiLineString Create(this GeographyFactory<GeographyMultiLineString> factory, List<List<GeographyPoint>> listOfPointList)
+        {
+            foreach (List<GeographyPoint> points in listOfPointList)
+            {
+                if (points.Count < 2)
+                {
+                    throw new JsonSerializationException($"Deserialization failed: GeoJson type '{GeoJsonConstants.MultiLineStringTypeName}' must contain at least two points.");
+                }
+
+                factory = factory.LineString();
+
+                foreach (GeographyPoint point in points)
+                {
+                    factory = factory.LineTo(point.Latitude, point.Longitude);
+                }
+            }
+
+            GeographyMultiLineString result = factory.Build();
+
+            return result;
+        }
+
+        public static GeographyMultiPolygon Create(this GeographyFactory<GeographyMultiPolygon> factory, List<List<List<GeographyPoint>>> points)
+        {
+            foreach (List<List<GeographyPoint>> polygon in points)
+            {
+                factory = factory.Polygon();
+
+                foreach (List<GeographyPoint> ring in polygon)
+                {
+                    factory = factory.Ring(ring[0].Latitude, ring[0].Longitude);
+
+                    for (int i = 1; i < ring.Count - 1; i++)
+                    {
+                        factory = factory.LineTo(ring[i].Latitude, ring[i].Longitude);
+                    }
+                }
+            }
+
+            GeographyMultiPolygon result = factory.Build();
+
+            return result;
+        }
+
+        public static GeographyCollection Create(this GeographyFactory<GeographyCollection> factory, List<Geography> geographies)
+        {
+            foreach (Geography geography in geographies)
+            {
+                factory.Add(geography);
+            }
+
+            return factory.Build();
+        }
+    }
+}