com.tinkerpop.gremlin.structure.Vertex Maven / Gradle / Ivy

Go to download
package com.tinkerpop.gremlin.structure;

import com.tinkerpop.gremlin.process.T;
import com.tinkerpop.gremlin.process.Traversal;
import com.tinkerpop.gremlin.process.Traverser;
import com.tinkerpop.gremlin.process.graph.GraphTraversal;
import com.tinkerpop.gremlin.process.graph.step.map.StartStep;
import com.tinkerpop.gremlin.util.function.SBiPredicate;
import com.tinkerpop.gremlin.util.function.SConsumer;
import com.tinkerpop.gremlin.util.function.SFunction;
import com.tinkerpop.gremlin.util.function.SPredicate;

import java.util.Iterator;
import java.util.Map;

/**
 * A {@link Vertex} maintains pointers to both a set of incoming and outgoing {@link Edge} objects. The outgoing edges
 * are those edges for  which the {@link Vertex} is the tail. The incoming edges are those edges for which the
 * {@link Vertex} is the head.
 * 
 * Diagrammatically:
 * 
 * ---inEdges---> vertex ---outEdges--->.
 * 
 *
 * @author Marko A. Rodriguez (http://markorodriguez.com)
 * @author Joshua Shinavier (http://fortytwo.net)
 */
public interface Vertex extends Element {

    /**
     * The default label to use for a vertex.
     */
    public static final String DEFAULT_LABEL = "vertex";

    /**
     * Add an outgoing edge to the vertex with provided label and edge properties as key/value pairs.
     * These key/values must be provided in an even number where the odd numbered arguments are {@link String}
     * property keys and the even numbered arguments are the related property values.  Hidden properties can be
     * set by specifying the key as {@link com.tinkerpop.gremlin.structure.Graph.Key#hide}.
     *
     * @param label     The label of the edge
     * @param inVertex  The vertex to receive an incoming edge from the current vertex
     * @param keyValues The key/value pairs to turn into edge properties
     * @return the newly created edge
     */
    public Edge addEdge(final String label, final Vertex inVertex, final Object... keyValues);

    /**
     * The following iterators need to be implemented by the vendor as these define how edges are
     * retrieved off of a vertex. All other steps are derivatives of this and thus, defaulted in Vertex.
     */

    /**
     * @param direction    The incident direction of the edges to retrieve off this vertex
     * @param branchFactor The max number of edges to retrieve
     * @param labels       The labels of the edges to retrieve
     * @return An iterator of edges meeting the provided specification
     */
    public Iterator edges(final Direction direction, final int branchFactor, final String... labels);

    /**
     * @param direction    The adjacency direction of the vertices to retrieve off this vertex
     * @param branchFactor The max number of vertices to retrieve
     * @param labels       The labels of the edges associated with the vertices to retrieve
     * @return An iterator of vertices meeting the provided specification
     */
    public Iterator vertices(final Direction direction, final int branchFactor, final String... labels);

    /**
     * The following steps are Vertex specific and have default implementations based on the vendor implementations above.
     */

    public default GraphTraversal to(final Direction direction, final int branchFactor, final String... labels) {
        return this.start().to(direction, branchFactor, labels);
    }

    public default GraphTraversal toE(final Direction direction, final int branchFactor, final String... labels) {
        return this.start().toE(direction, branchFactor, labels);
    }

    public default GraphTraversal to(final Direction direction, final String... labels) {
        return this.to(direction, Integer.MAX_VALUE, labels);
    }

    public default GraphTraversal toE(final Direction direction, final String... labels) {
        return this.toE(direction, Integer.MAX_VALUE, labels);
    }

    public default GraphTraversal out(final int branchFactor, final String... labels) {
        return this.to(Direction.OUT, branchFactor, labels);
    }

    public default GraphTraversal in(final int branchFactor, final String... labels) {
        return this.to(Direction.IN, branchFactor, labels);
    }

    public default GraphTraversal both(final int branchFactor, final String... labels) {
        return this.to(Direction.BOTH, branchFactor, labels);
    }

    public default GraphTraversal outE(final int branchFactor, final String... labels) {
        return this.toE(Direction.OUT, branchFactor, labels);
    }

    public default GraphTraversal inE(final int branchFactor, final String... labels) {
        return this.toE(Direction.IN, branchFactor, labels);
    }

    public default GraphTraversal bothE(final int branchFactor, final String... labels) {
        return this.toE(Direction.BOTH, branchFactor, labels);
    }

    public default GraphTraversal out(final String... labels) {
        return this.to(Direction.OUT, Integer.MAX_VALUE, labels);
    }

    public default GraphTraversal in(final String... labels) {
        return this.to(Direction.IN, Integer.MAX_VALUE, labels);
    }

    public default GraphTraversal both(final String... labels) {
        return this.to(Direction.BOTH, Integer.MAX_VALUE, labels);
    }

    public default GraphTraversal outE(final String... labels) {
        return this.toE(Direction.OUT, Integer.MAX_VALUE, labels);
    }

    public default GraphTraversal inE(final String... labels) {
        return this.toE(Direction.IN, Integer.MAX_VALUE, labels);
    }

    public default GraphTraversal bothE(final String... labels) {
        return this.toE(Direction.BOTH, Integer.MAX_VALUE, labels);
    }

    /**
     * The following steps are general to element but repeated here for the sake of ensuring property type casting.
     */

    public default GraphTraversal aggregate(final SFunction preAggregateFunction) {
        return this.start().aggregate(preAggregateFunction);
    }

    public default GraphTraversal aggregate() {
        return this.start().aggregate();
    }

    public default GraphTraversal store(final SFunction preStoreFunction) {
        return this.start().store(preStoreFunction);
    }

    public default GraphTraversal store() {
        return this.start().store();
    }

    public default GraphTraversal as(final String as) {
        return this.start().as(as);
    }

    public default GraphTraversal filter(final SPredicate> predicate) {
        return this.start().filter(predicate);
    }

    public default  GraphTraversal flatMap(final SFunction, Iterator> function) {
        return this.start().flatMap(function);
    }

    public default  GraphTraversal has(final String key) {
        return this.start().has(key);
    }

    public default  GraphTraversal has(final String key, final Object value) {
        return this.start().has(key, value);
    }

    public default  GraphTraversal has(final String key, final T t, final Object value) {
        return this.start().has(key, t, value);
    }

    public default  GraphTraversal has(final String key, final SBiPredicate predicate, final Object value) {
        return this.start().has(key, predicate, value);
    }

    public default  GraphTraversal hasNot(final String key) {
        return this.start().hasNot(key);
    }

    public default  GraphTraversal interval(final String key, final Comparable startValue, final Comparable endValue) {
        return this.start().interval(key, startValue, endValue);
    }

    public default GraphTraversal identity() {
        return this.start().identity();
    }

    public default GraphTraversal jump(final String as) {
        return this.start().jump(as);
    }

    public default GraphTraversal jump(final String as, final SPredicate> ifPredicate) {
        return this.start().jump(as, ifPredicate);
    }

    public default GraphTraversal jump(final String as, final SPredicate> ifPredicate, final SPredicate> emitPredicate) {
        return this.start().jump(as, ifPredicate, emitPredicate);
    }

    public default  GraphTraversal map(final SFunction, E2> function) {
        return this.start().map(function);
    }

    public default  GraphTraversal> match(final String inAs, final Traversal... traversals) {
        return (GraphTraversal) this.start().match(inAs, traversals);
    }

    public default GraphTraversal sideEffect(final SConsumer> consumer) {
        return this.start().sideEffect(consumer);
    }

    public default  GraphTraversal choose(final SPredicate> choosePredicate, final Traversal trueChoice, final Traversal falseChoice) {
        return this.start().choose(choosePredicate, trueChoice, falseChoice);
    }

    public default  GraphTraversal choose(final SFunction, M> mapFunction, final Map> choices) {
        return this.start().choose(mapFunction, choices);
    }

    public default GraphTraversal with(final Object... variableValues) {
        return this.start().with(variableValues);
    }

    public default GraphTraversal start() {
        final GraphTraversal traversal = GraphTraversal.of();
        return (GraphTraversal) traversal.addStep(new StartStep<>(traversal, this));
    }

    ///////////////

    /**
     * Common exceptions to use with a vertex.
     */
    public static class Exceptions {
        public static UnsupportedOperationException userSuppliedIdsNotSupported() {
            return new UnsupportedOperationException("Vertex does not support user supplied identifiers");
        }

        public static IllegalStateException vertexRemovalNotSupported() {
            return new IllegalStateException("Vertex removal are not supported");
        }

        public static IllegalStateException edgeAdditionsNotSupported() {
            return new IllegalStateException("Edge additions not supported");
        }
    }
}