Java tutorial
/* * 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.commons.configuration.Configuration; import org.apache.tinkerpop.gremlin.process.computer.GraphComputer; import org.apache.tinkerpop.gremlin.process.remote.traversal.step.map.RemoteStep; import org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal; import org.apache.tinkerpop.gremlin.process.traversal.step.TraversalParent; import org.apache.tinkerpop.gremlin.process.traversal.step.sideEffect.ProfileSideEffectStep; import org.apache.tinkerpop.gremlin.process.traversal.step.sideEffect.SideEffectCapStep; import org.apache.tinkerpop.gremlin.process.traversal.step.util.BulkSet; import org.apache.tinkerpop.gremlin.process.traversal.step.util.EmptyStep; import org.apache.tinkerpop.gremlin.process.traversal.traverser.TraverserRequirement; import org.apache.tinkerpop.gremlin.process.traversal.util.TraversalExplanation; import org.apache.tinkerpop.gremlin.process.traversal.util.TraversalHelper; import org.apache.tinkerpop.gremlin.process.traversal.util.TraversalMetrics; import org.apache.tinkerpop.gremlin.structure.Graph; import java.io.Serializable; import java.util.ArrayList; import java.util.Collection; import java.util.HashSet; import java.util.Iterator; import java.util.List; import java.util.NoSuchElementException; import java.util.Optional; import java.util.Set; import java.util.Spliterator; import java.util.Spliterators; import java.util.concurrent.CompletableFuture; import java.util.function.Consumer; import java.util.function.Function; import java.util.stream.Stream; import java.util.stream.StreamSupport; /** * A {@link Traversal} represents a directed walk over a {@link Graph}. * This is the base interface for all traversal's, where each extending interface is seen as a domain specific language. * For example, {@link GraphTraversal} is a domain specific language for traversing a graph using "graph concepts" (e.g. vertices, edges). * Another example may represent the graph using "social concepts" (e.g. people, cities, artifacts). * A {@link Traversal} is evaluated in one of two ways: iterator-based OLTP or {@link GraphComputer}-based OLAP. * OLTP traversals leverage an iterator and are executed within a single JVM (with data access allowed to be remote). * OLAP traversals leverage {@link GraphComputer} and are executed between multiple JVMs (and/or cores). * * @author Marko A. Rodriguez (http://markorodriguez.com) */ public interface Traversal<S, E> extends Iterator<E>, Serializable, Cloneable, AutoCloseable { public static class Symbols { private Symbols() { // static fields only } public static final String profile = "profile"; } /** * Get access to administrative methods of the traversal via its accompanying {@link Traversal.Admin}. * * @return the admin of this traversal */ public default Traversal.Admin<S, E> asAdmin() { return (Traversal.Admin<S, E>) this; } /** * Return an {@link Optional} of the next E object in the traversal. * If the traversal is empty, then an {@link Optional#empty()} is returned. * * @return an optional of the next object in the traversal */ public default Optional<E> tryNext() { return this.hasNext() ? Optional.of(this.next()) : Optional.empty(); } /** * Get the next n-number of results from the traversal. * If the traversal has less than n-results, then only that number of results are returned. * * @param amount the number of results to get * @return the n-results in a {@link List} */ public default List<E> next(final int amount) { final List<E> result = new ArrayList<>(); int counter = 0; while (counter++ < amount && this.hasNext()) { result.add(this.next()); } return result; } /** * Put all the results into an {@link ArrayList}. * * @return the results in a list */ public default List<E> toList() { return this.fill(new ArrayList<>()); } /** * Put all the results into a {@link HashSet}. * * @return the results in a set */ public default Set<E> toSet() { return this.fill(new HashSet<>()); } /** * Put all the results into a {@link BulkSet}. * This can reduce both time and space when aggregating results by ensuring a weighted set. * * @return the results in a bulk set */ public default BulkSet<E> toBulkSet() { return this.fill(new BulkSet<>()); } /** * Return the traversal as a {@link Stream}. * * @return the traversal as a stream. */ public default Stream<E> toStream() { return StreamSupport.stream( Spliterators.spliteratorUnknownSize(this, Spliterator.IMMUTABLE | Spliterator.SIZED), false); } /** * Starts a promise to execute a function on the current {@code Traversal} that will be completed in the future. * Note that this method can only be used if the {@code Traversal} is constructed using * {@link TraversalSource#withRemote(Configuration)}. Calling this method otherwise will yield an * {@code IllegalStateException}. */ public default <T> CompletableFuture<T> promise(final Function<Traversal<S, E>, T> traversalFunction) { // apply strategies to see if RemoteStrategy has any effect (i.e. add RemoteStep) if (!this.asAdmin().isLocked()) this.asAdmin().applyStrategies(); // use the end step so the results are bulked final Step<?, E> endStep = this.asAdmin().getEndStep(); if (endStep instanceof RemoteStep) { return ((RemoteStep) endStep).promise().thenApply(traversalFunction); } else { throw new IllegalStateException( "Only traversals created using withRemote() can be used in an async way"); } } /** * Add all the results of the traversal to the provided collection. * * @param collection the collection to fill * @return the collection now filled */ public default <C extends Collection<E>> C fill(final C collection) { try { if (!this.asAdmin().isLocked()) this.asAdmin().applyStrategies(); // use the end step so the results are bulked final Step<?, E> endStep = this.asAdmin().getEndStep(); while (true) { final Traverser<E> traverser = endStep.next(); TraversalHelper.addToCollection(collection, traverser.get(), traverser.bulk()); } } catch (final NoSuchElementException ignored) { } return collection; } /** * Iterate all the {@link Traverser} instances in the traversal. * What is returned is the empty traversal. * It is assumed that what is desired from the computation is are the sideEffects yielded by the traversal. * * @return the fully drained traversal */ public default <A, B> Traversal<A, B> iterate() { try { if (!this.asAdmin().isLocked()) this.asAdmin().applyStrategies(); // use the end step so the results are bulked final Step<?, E> endStep = this.asAdmin().getEndStep(); while (true) { endStep.next(); } } catch (final NoSuchElementException ignored) { } return (Traversal<A, B>) this; } /** * Profile the traversal. * * @return the updated traversal with respective {@link ProfileSideEffectStep}. */ public default Traversal<S, TraversalMetrics> profile() { this.asAdmin().getBytecode().addStep(Symbols.profile); return this.asAdmin() .addStep(new ProfileSideEffectStep<>(this.asAdmin(), ProfileSideEffectStep.DEFAULT_METRICS_KEY)) .addStep(new SideEffectCapStep<Object, TraversalMetrics>(this.asAdmin(), ProfileSideEffectStep.DEFAULT_METRICS_KEY)); } /** * Return a {@link TraversalExplanation} that shows how this traversal will mutate with each applied {@link TraversalStrategy}. * * @return a traversal explanation */ public default TraversalExplanation explain() { if (this.asAdmin().isLocked()) throw new IllegalStateException( "The traversal is locked and can not be explained on a strategy-by-strategy basis"); return new TraversalExplanation(this.asAdmin()); } /** * A traversal can be rewritten such that its defined end type E may yield objects of a different type. * This helper method allows for the casting of the output to the known the type. * * @param endType the true output type of the traversal * @param consumer a {@link Consumer} to process each output * @param <E2> the known output type of the traversal */ public default <E2> void forEachRemaining(final Class<E2> endType, final Consumer<E2> consumer) { try { while (true) { consumer.accept((E2) next()); } } catch (final NoSuchElementException ignore) { } } @Override public default void forEachRemaining(final Consumer<? super E> action) { try { while (true) { action.accept(next()); } } catch (final NoSuchElementException ignore) { } } /** * Releases resources opened in any steps that implement {@link AutoCloseable}. */ @Override public default void close() throws Exception { for (final Step<?, ?> step : this.asAdmin().getSteps()) { if (step instanceof AutoCloseable) ((AutoCloseable) step).close(); } } /** * A collection of {@link Exception} types associated with Traversal execution. */ public static class Exceptions { public static IllegalStateException traversalIsLocked() { return new IllegalStateException( "The traversal strategies are complete and the traversal can no longer be modulated"); } public static IllegalStateException traversalIsNotReversible() { return new IllegalStateException( "The traversal is not reversible as it contains steps that are not reversible"); } } public interface Admin<S, E> extends Traversal<S, E> { /** * Get the {@link Bytecode} associated with the construction of this traversal. * * @return the byte code representation of the traversal */ public Bytecode getBytecode(); /** * Add an iterator of {@link Traverser.Admin} objects to the head/start of the traversal. * Users should typically not need to call this method. For dynamic inject of data, they should use {@link org.apache.tinkerpop.gremlin.process.traversal.step.sideEffect.InjectStep}. * * @param starts an iterators of traversers */ public default void addStarts(final Iterator<Traverser.Admin<S>> starts) { if (!this.isLocked()) this.applyStrategies(); this.getStartStep().addStarts(starts); } /** * Add a single {@link Traverser.Admin} object to the head of the traversal. * Users should typically not need to call this method. For dynamic inject of data, they should use {@link org.apache.tinkerpop.gremlin.process.traversal.step.sideEffect.InjectStep}. * * @param start a traverser to add to the traversal */ public default void addStart(final Traverser.Admin<S> start) { if (!this.isLocked()) this.applyStrategies(); this.getStartStep().addStart(start); } /** * Get the {@link Step} instances associated with this traversal. * The steps are ordered according to their linked list structure as defined by {@link Step#getPreviousStep()} and {@link Step#getNextStep()}. * * @return the ordered steps of the traversal */ public List<Step> getSteps(); /** * Add a {@link Step} to the end of the traversal. This method should link the step to its next and previous step accordingly. * * @param step the step to add * @param <E2> the output of the step * @return the updated traversal * @throws IllegalStateException if the {@link TraversalStrategies} have already been applied */ public default <E2> Traversal.Admin<S, E2> addStep(final Step<?, E2> step) throws IllegalStateException { return this.addStep(this.getSteps().size(), step); } /** * Add a {@link Step} to an arbitrary point in the traversal. * * @param index the location in the traversal to insert the step * @param step the step to add * @param <S2> the new start type of the traversal (if the added step was a start step) * @param <E2> the new end type of the traversal (if the added step was an end step) * @return the newly modulated traversal * @throws IllegalStateException if the {@link TraversalStrategies} have already been applied */ public <S2, E2> Traversal.Admin<S2, E2> addStep(final int index, final Step<?, ?> step) throws IllegalStateException; /** * Remove a {@link Step} from the traversal. * * @param step the step to remove * @param <S2> the new start type of the traversal (if the removed step was a start step) * @param <E2> the new end type of the traversal (if the removed step was an end step) * @return the newly modulated traversal * @throws IllegalStateException if the {@link TraversalStrategies} have already been applied */ public default <S2, E2> Traversal.Admin<S2, E2> removeStep(final Step<?, ?> step) throws IllegalStateException { return this.removeStep(TraversalHelper.stepIndex(step, this)); } /** * Remove a {@link Step} from the traversal. * * @param index the location in the traversal of the step to be evicted * @param <S2> the new start type of the traversal (if the removed step was a start step) * @param <E2> the new end type of the traversal (if the removed step was an end step) * @return the newly modulated traversal * @throws IllegalStateException if the {@link TraversalStrategies} have already been applied */ public <S2, E2> Traversal.Admin<S2, E2> removeStep(final int index) throws IllegalStateException; /** * Get the start/head of the traversal. If the traversal is empty, then an {@link EmptyStep} instance is returned. * * @return the start step of the traversal */ public default Step<S, ?> getStartStep() { final List<Step> steps = this.getSteps(); return steps.isEmpty() ? EmptyStep.instance() : steps.get(0); } /** * Get the end/tail of the traversal. If the traversal is empty, then an {@link EmptyStep} instance is returned. * * @return the end step of the traversal */ public default Step<?, E> getEndStep() { final List<Step> steps = this.getSteps(); return steps.isEmpty() ? EmptyStep.instance() : steps.get(steps.size() - 1); } /** * Apply the registered {@link TraversalStrategies} to the traversal. * Once the strategies are applied, the traversal is "locked" and can no longer have steps added to it. * The order of operations for strategy applications should be: globally id steps, apply strategies to root traversal, then to nested traversals. * * @throws IllegalStateException if the {@link TraversalStrategies} have already been applied */ public void applyStrategies() throws IllegalStateException; /** * Get the {@link TraverserGenerator} associated with this traversal. * The traversal generator creates {@link Traverser} instances that are respective of the traversal's {@link org.apache.tinkerpop.gremlin.process.traversal.traverser.TraverserRequirement}. * * @return the generator of traversers */ public TraverserGenerator getTraverserGenerator(); /** * Get the set of all {@link TraverserRequirement}s for this traversal. * * @return the features of a traverser that are required to execute properly in this traversal */ public Set<TraverserRequirement> getTraverserRequirements(); /** * Call the {@link Step#reset} method on every step in the traversal. */ public default void reset() { this.getSteps().forEach(Step::reset); } /** * Set the {@link TraversalSideEffects} of this traversal. * * @param sideEffects the sideEffects to set for this traversal. */ public void setSideEffects(final TraversalSideEffects sideEffects); /** * Get the {@link TraversalSideEffects} associated with the traversal. * * @return The traversal sideEffects */ public TraversalSideEffects getSideEffects(); /** * Set the {@link TraversalStrategies} to be used by this traversal at evaluation time. * * @param strategies the strategies to use on this traversal */ public void setStrategies(final TraversalStrategies strategies); /** * Get the {@link TraversalStrategies} associated with this traversal. * * @return the strategies associated with this traversal */ public TraversalStrategies getStrategies(); /** * Set the {@link org.apache.tinkerpop.gremlin.process.traversal.step.TraversalParent} {@link Step} that is the parent of this traversal. * Traversals can be nested and this is the means by which the traversal tree is connected. * * @param step the traversal holder parent step */ public void setParent(final TraversalParent step); /** * Get the {@link org.apache.tinkerpop.gremlin.process.traversal.step.TraversalParent} {@link Step} that is the parent of this traversal. * Traversals can be nested and this is the means by which the traversal tree is walked. * * @return the traversal holder parent step */ public TraversalParent getParent(); /** * Cloning is used to duplicate the traversal typically in OLAP environments. * * @return The cloned traversal */ @SuppressWarnings("CloneDoesntDeclareCloneNotSupportedException") public Traversal.Admin<S, E> clone(); /** * When the traversal has had its {@link TraversalStrategies} applied to it, it is locked. * * @return whether the traversal is locked */ public boolean isLocked(); public Optional<Graph> getGraph(); public void setGraph(final Graph graph); public default boolean equals(final Traversal.Admin<S, E> other) { final List<Step> steps = this.getSteps(); final List<Step> otherSteps = other.getSteps(); if (steps.size() == otherSteps.size()) { for (int i = 0; i < steps.size(); i++) { if (!steps.get(i).equals(otherSteps.get(i))) { return false; } } return true; } return false; } public default Traverser.Admin<E> nextTraverser() { return this.getEndStep().next(); } } }