spmallette commented on a change in pull request #1574: URL: https://github.com/apache/tinkerpop/pull/1574#discussion_r821091174
########## 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> { + + /** + * The service factory creates instances of callable services based on the desired execution type. Some services + * (e.g. full text search) might be run at the start of a traversal or mid-traversal. The service factory + * will create an instance based on how the service will be executed. This leaves open the possibility for + * a single named service to support multiple execution modes (streaming vs. chunked vs. all-at-once) and + * dynamically choose one based on the location in the traversal of the service call and the static parameters + * supplied (this allow for dynamic chunk size). + */ + interface ServiceFactory<I, R> { + + /** + * Get the name of this service. + */ + String getName(); + + /** + * Get the execution modes that it supports. + */ + Set<Type> getSupportedTypes(); + + /** + * Return a description of any service call parameters. + */ + default Map describeParams() { + return Collections.emptyMap(); + } + + /** + * Return any {@link TraverserRequirement}s necessary for this service call for each execution {@link Type} + * it supports. + */ + default Map<Type,Set<TraverserRequirement>> getRequirementsByType() { + return Collections.emptyMap(); + } + + /** + * Return any {@link TraverserRequirement}s necessary for this service call for the supplied execution + * {@link Type}. + */ + default Set<TraverserRequirement> getRequirements(final Type type) { + return getRequirementsByType().getOrDefault(type, Collections.emptySet()); + } + + /** + * Create a Service call instance. + * + * @param isStart true if the call is being used to start a traversal + * @param params the static params provided to service call (if any) + * @return the service call instance + */ + Service<I, R> createService(final boolean isStart, final Map params); + + } + + /** + * Service calls can appear at the start of a traversal or mid-traversal. If mid-traversal, they can operate in a + * streaming fashion or as a barrier. A Tinkerpop service instance can only operate in one of those three modes, + * however if the underlying service can do multiple modes, it can be registered using a {@link ServiceFactory} + * capable of providing service instances for the supported types. + */ + enum Type { + /** + * Start the traversal with no upstream input. + */ + Start, + + /** + * Mid-traversal with streaming input. + */ + Streaming, + + /** + * Mid-traversal with all-at-once input. + */ + Barrier; + } + + /** + * Return the {@link Type} of service call. + */ + Type getType(); + + /** + * Return any {@link TraverserRequirement}s necessary for this service call. + */ + default Set<TraverserRequirement> getRequirements() { + return Collections.emptySet(); + } + + /** + * True if Start type. + */ + default boolean isStart() { + return getType() == Type.Start; + } + + /** + * True if Streaming type. + */ + default boolean isStreaming() { + return getType() == Type.Streaming; + } + + /** + * True if Barrier type. + */ + default boolean isBarrier() { + return getType() == Type.Barrier; + } + + /** + * Return the max barrier size. Default is all upstream solutions. + */ + default int getMaxBarrierSize() { + return Integer.MAX_VALUE; + } + + /** + * Execute a Start service call. + */ + default CloseableIterator<R> execute(ServiceCallContext ctx, Map params) { Review comment: nit: `final` -- 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]
