[ 
https://issues.apache.org/jira/browse/TINKERPOP-2558?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18147802#comment-18147802
 ] 

ASF GitHub Bot commented on TINKERPOP-2558:
-------------------------------------------

Cole-Greer commented on code in PR #3809:
URL: https://github.com/apache/tinkerpop/pull/3809#discussion_r4633902185


##########
gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/GeoP.java:
##########
@@ -0,0 +1,238 @@
+/*
+ * 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.tinkerpop.gremlin.process.traversal;
+
+import org.apache.tinkerpop.gremlin.process.traversal.step.GValue;
+import org.apache.tinkerpop.gremlin.structure.geo.Geometry;
+import org.apache.tinkerpop.gremlin.structure.geo.Model;
+
+import java.util.HashMap;
+
+/**
+ * Predefined {@code Predicate} values that filter {@link Geometry} values by 
a spatial
+ * relationship, backed by the {@link Geo} predicates.
+ * <p>
+ * An argument may instead come from a child traversal, which is resolved 
against each traverser.
+ * An argument may also be a {@link GValue}, whose value is resolved when the 
traversal is built.
+ * <p>
+ * <b>Accuracy in the geographic model.</b> Shapes are related in longitude 
and latitude, with
+ * edges straight in both, so the predicates hold for edges under about 100 km 
that cross neither
+ * the antimeridian nor a pole.
+ *
+ * @since 4.0.0
+ */
+public class GeoP extends P<Geometry> {
+
+    /**
+     * Constructs a {@code GeoP} from the given geometry, which is validated 
as a constant. A
+     * geometry resolved at runtime is given as a child traversal instead.
+     *
+     * @since 4.0.0
+     */
+    public GeoP(final PBiPredicate<Object, Object> biPredicate, final Object 
value) {
+        super(asGeometryPredicate(biPredicate), 
GeoP.<Geometry>validatedValue(biPredicate, value));
+    }
+
+    /**
+     * Constructs a {@code GeoP} with a child traversal whose result is 
resolved at runtime against
+     * the current traverser.
+     *
+     * @since 4.0.0
+     */
+    public GeoP(final PBiPredicate<Object, Object> biPredicate, final 
Traversal.Admin<?, ?> traversalValue) {
+        super(asGeometryPredicate(biPredicate), traversalValue);
+    }
+
+    /**
+     * Constructs a {@code GeoP} from a variable, whose value is validated 
once it is resolved.
+     *
+     * @since 4.0.0
+     */
+    public GeoP(final PBiPredicate<Object, Object> biPredicate, final 
GValue<?> value) {
+        super(asGeometryPredicate(biPredicate), asGeometryVariable(value));
+        validateConstants(biPredicate, null == value ? null : value.get());
+    }
+
+    @Override
+    public boolean equals(final Object other) {
+        return other instanceof GeoP && super.equals(other);
+    }
+
+    @Override
+    public P<Geometry> negate() {
+        return new NotP<>(this);
+    }
+
+    public GeoP clone() {
+        final GeoP clone = (GeoP) super.clone();
+        clone.variables = new HashMap<>(variables);
+        return clone;
+    }
+
+    /**
+     * {@inheritDoc}
+     * <p>
+     * A new value for one of this predicate's variables is validated as the 
same value given to a
+     * constructor would be, before it is kept.
+     */
+    @Override
+    public void updateVariable(final String name, final Object value) {
+        if (!variables.containsKey(name)) return;
+
+        validateConstants(biPredicate, value);
+
+        super.updateVariable(name, value);
+    }
+
+    /**
+     * {@inheritDoc}
+     * <p>
+     * A value other than a child traversal is validated as the same value 
given to a constructor would be.
+     */
+    @Override
+    protected void validateValue(final Object value) {
+        if (value instanceof Traversal) return;

Review Comment:
   There is an inconsistency here between this method (passing all Traversal's 
and unboxing GValue's), and `private static <V> V validatedValue(final 
PBiPredicate<Object, Object> biPredicate, final Object value)` which always 
throws on both.
   
   As I understand, the static forms of these methods only exist so that 
arguments can be validated prior to passing them into `super()` in the 
constructors here. I don't think that's necessary, as the `super()` constructor 
itself defers to `setValue()`, which in turn will call the new `protected void 
validateValue(final Object value)`.
   
   The current implementation appears to work fine, as the static factory 
methods below all route to appropriate constructors, but this is a good 
refactor opportunity.



##########
docs/src/data/the-delivery.asciidoc:
##########
@@ -0,0 +1,145 @@
+////
+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.
+////
+[[the-delivery]]
+[llms-summary="The delivery graph: a TinkerPop 4.x showcase for geometry 
property values and the geospatial predicates. Includes its GQL Graph Types 
schema and Gremlin examples that filter vertices and edges by location with 
geoWithin and geoContains. Only the loading block runs at build time. The 
examples are static listings with their results in callouts."]
+== The Delivery Graph
+
+The delivery graph models a grocery delivery company. It runs five hubs: 
`Hell's Kitchen`,
+`Williamsburg` and `Los Angeles` in the United States, `Greenwich` in the 
United Kingdom, and
+`Auckland` in New Zealand. Every hub apart from Los Angeles `serves` a 
delivery zone, customers
+such as `Ana` and `Dee` place orders that are `orderedFrom` a hub, and the 
hubs ship stock to one
+another over `shipsTo` lanes running from about 3,900 km up to nearly half the 
circumference of the
+Earth. Inside the Hell's Kitchen hub is a small warehouse mapped in meters, 
where the picker `Pat`
+works.
+
+The graph was created for TinkerPop 4.x to demonstrate `Geometry` property 
values and the geospatial
+predicates `geoWithin` and `geoContains`. Every vertex carries its location in 
a `loc` property, and
+the `delivered` and `shipsTo` edges carry their route in a `path` property. 
Locations on the Earth
+use the `GEOGRAPHIC` model with longitude and latitude in degrees, while the
+warehouse uses the `CARTESIAN` model with coordinates in meters. It is the 
reference example for
+filtering by location, because each geometry exercises a case that spatial 
filters commonly get
+wrong: a zone with a hole, a customer on a border, a zone across the prime 
meridian, a zone in two
+parts, a shipping lane across the antimeridian, z values including z = 0, 
overlapping zones, and an
+invalid polygon. It is created with `TinkerFactory.createTheDelivery()` and, 
because geometry
+serialization is not yet available, has no data file.
+
+.The Delivery Graph
+image::the-delivery-graph.png[width=685]
+
+=== Schema
+
+[source,gql]
+----
+

> GEO Spatial APIs
> ----------------
>
>                 Key: TINKERPOP-2558
>                 URL: https://issues.apache.org/jira/browse/TINKERPOP-2558
>             Project: TinkerPop
>          Issue Type: Improvement
>          Components: process
>    Affects Versions: 3.5.0
>            Reporter: Jitesh
>            Priority: Major
>
> Provide support for Geo based APIs (predicates, objects, etc)
>  
>  



--
This message was sent by Atlassian Jira
(v10.3.26#10030026)

Reply via email to