divijvaidya commented on a change in pull request #1574: URL: https://github.com/apache/tinkerpop/pull/1574#discussion_r823902435
########## File path: gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/ElementStep.java ########## @@ -0,0 +1,48 @@ +/* + * 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.step.map; + +import org.apache.tinkerpop.gremlin.process.traversal.Traversal; +import org.apache.tinkerpop.gremlin.process.traversal.Traverser; +import org.apache.tinkerpop.gremlin.process.traversal.traverser.TraverserRequirement; +import org.apache.tinkerpop.gremlin.structure.Element; +import org.apache.tinkerpop.gremlin.structure.Property; + +import java.util.Collections; +import java.util.Set; + +/** + * @author Mike Personick (http://github.com/mikepersonick) + */ +public final class ElementStep<P extends Property, E extends Element> extends ScalarMapStep<P, E> { Review comment: please add java doc ########## File path: docs/src/dev/provider/gremlin-semantics.asciidoc ########## @@ -488,6 +488,107 @@ fully demonstrative of Gremlin step semantics. It is also hard to simply read th step is meant to behave. This section discusses the semantics for individual steps to help users and providers understand implementation expectations. +=== call() + +*Description:* Provides support for provider-specific service calls. + +*Syntax:* `call()` | `call(String, Map)` | `call(String, Traversal)` | `call(String, Map, Traversal)` Review comment: What impact does this step has on path? e.g. what does g.V().call().path() display? ########## File path: docs/src/dev/provider/gremlin-semantics.asciidoc ########## @@ -488,6 +488,107 @@ fully demonstrative of Gremlin step semantics. It is also hard to simply read th step is meant to behave. This section discusses the semantics for individual steps to help users and providers understand implementation expectations. +=== call() + +*Description:* Provides support for provider-specific service calls. + +*Syntax:* `call()` | `call(String, Map)` | `call(String, Traversal)` | `call(String, Map, Traversal)` + +[width="100%",options="header"] +|========================================================= +|Start Step |Mid Step |Modulated |Domain |Range +|Y |Y |`with()` |`any` |`any` +|========================================================= + +*Arguments:* + +* `String` - The name of the service call. +* `Map` - A collection of static parameters relevant to the particular service call. +* `Traversal` - A traversal used to dynamically build at query time a collection of parameters relevant to the service +call. + +*Modulation:* + +* `with(key, value)` - Sets an additional static parameter relevant to the service call. Review comment: What is the range of types applicable to value here? ########## File path: docs/src/upgrade/release-3.6.x.asciidoc ########## @@ -794,5 +794,42 @@ Feature tags have been introduced for feature tests that stress these new semant A new GraphFeature has been added "OrderabilitySemantics" to signify compliance with the new comparability/orderability semantics. -See: link:https://tinkerpop.apache.org/docs/3.6.0/dev/provider/#_gremlin_semantics[Gremlin Semantics] -See: link:https://tinkerpop.apache.org/docs/3.6.0/dev/developer/#_for_committers[Developer Documentation] +See: link:https://tinkerpop.apache.org/docs/3.6.0/dev/provider/#gremlin-semantics-concepts[Gremlin Semantics] + +===== Service Call API + +3.6 introduces a `call()` API that allows providers to provide custom service calls with their implementation. Providers +using the reference implementation for `Traversal` execution will implement the `ServiceFactory` and `Service` +interfaces for each named service they provide. Providers using their own query engines for traveral execution will need +to provide a call operation that can list the available services (directory service) and execute named services. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-2680[TINKERPOP-2680] +link:https://tinkerpop.apache.org/docs/3.6.0/reference/#element-step[Reference Documentation] +link:https://tinkerpop.apache.org/docs/3.6.0/dev/provider/#_call[Provider Documentation] + +==== element() Step + +The new `element()` step provides a way to traverse from a `Property` to the `Element` that owns it: + +[source,text] +---- +// VertexProperty -> Vertex +gremlin> g.V(1).properties().limit(1).element() +==>v[1] + +// Property -> Edge +gremlin> g.E(7).properties().element() +==>e[7][1-knows->2] + +// Property -> VertexProperty +gremlin> g.V(1).property("a", "b") Review comment: please add an example with path() as well to demonstrate how the path element changes as well. ########## File path: gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/service/Service.java ########## @@ -0,0 +1,287 @@ +/* + * 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.structure.service; + +import org.apache.tinkerpop.gremlin.process.traversal.Step; +import org.apache.tinkerpop.gremlin.process.traversal.Traversal; +import org.apache.tinkerpop.gremlin.process.traversal.Traverser; +import org.apache.tinkerpop.gremlin.process.traversal.step.map.CallStep; +import org.apache.tinkerpop.gremlin.process.traversal.traverser.TraverserRequirement; +import org.apache.tinkerpop.gremlin.process.traversal.traverser.util.TraverserSet; +import org.apache.tinkerpop.gremlin.structure.util.CloseableIterator; + +import java.util.Collections; +import java.util.List; +import java.util.Map; +import java.util.Set; + +import static org.apache.tinkerpop.gremlin.util.tools.CollectionFactory.asMap; + +/** + * Service call with I input type and R return type. Services can return {@link Traverser}s or raw values (which will be + * converted into Traversers by {@link CallStep}. + * + * @author Mike Personick (http://github.com/mikepersonick) + */ +public interface Service<I, R> { Review comment: Do you think it's worth adding a teardown/unregister method to complete the service lifecycle since we "register" it at a point in time? ########## File path: gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/Graph.java ########## @@ -540,6 +550,14 @@ default boolean supportsOrderabilitySemantics() { return true; } + /** + * Determines if the {@code Graph} implementation supports the service call feature. + */ + @FeatureDescriptor(name = FEATURE_SERVICE_CALL) + default boolean supportsServiceCall() { + return true; Review comment: default should probably be false since the default service implementation is not very useful. ########## File path: docs/src/dev/provider/gremlin-semantics.asciidoc ########## @@ -488,6 +488,107 @@ fully demonstrative of Gremlin step semantics. It is also hard to simply read th step is meant to behave. This section discusses the semantics for individual steps to help users and providers understand implementation expectations. +=== call() + +*Description:* Provides support for provider-specific service calls. + +*Syntax:* `call()` | `call(String, Map)` | `call(String, Traversal)` | `call(String, Map, Traversal)` + +[width="100%",options="header"] +|========================================================= +|Start Step |Mid Step |Modulated |Domain |Range +|Y |Y |`with()` |`any` |`any` +|========================================================= + +*Arguments:* + +* `String` - The name of the service call. +* `Map` - A collection of static parameters relevant to the particular service call. +* `Traversal` - A traversal used to dynamically build at query time a collection of parameters relevant to the service +call. + +*Modulation:* + +* `with(key, value)` - Sets an additional static parameter relevant to the service call. +* `with(key, Traversal)` - Sets an additional dynamic parameter relevant to the service call. Review comment: Does this traversal always have to be a AnonymousTraversal or could it have a graphTraversalSource? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
