/*
* 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;
import org.apache.tinkerpop.gremlin.structure.util.Host;
import java.util.Iterator;
/**
* 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.
* <p/>
* Diagrammatically:
* <pre>
* ---inEdges---> vertex ---outEdges--->.
* </pre>
*
* @author Marko A. Rodriguez (http://markorodriguez.com)
* @author Stephen Mallette (http://stephen.genoprime.com)
*/
public interface Vertex extends Element, Host {
/**
* The default label to use for a vertex.
*/
public static final String DEFAULT_LABEL = "vertex";
static final Object[] EMPTY_ARGS = new Object[0];
/**
* 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.
*
* @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);
/**
* Get the {@link VertexProperty} for the provided key. If the property does not exist, return
* {@link VertexProperty#empty}. If there are more than one vertex properties for the provided
* key, then throw {@link Vertex.Exceptions#multiplePropertiesExistForProvidedKey}.
*
* @param key the key of the vertex property to get
* @param <V> the expected type of the vertex property value
* @return the retrieved vertex property
*/
@Override
public default <V> VertexProperty<V> property(final String key) {
final Iterator<VertexProperty<V>> iterator = this.properties(key);
if (iterator.hasNext()) {
final VertexProperty<V> property = iterator.next();
if (iterator.hasNext())
throw Vertex.Exceptions.multiplePropertiesExistForProvidedKey(key);
else
return property;
} else {
return VertexProperty.<V>empty();
}
}
/**
* Set the provided key to the provided value using {@link VertexProperty.Cardinality#single}.
*
* @param key the key of the vertex property
* @param value The value of the vertex property
* @param <V> the type of the value of the vertex property
* @return the newly created vertex property
*/
@Override
public default <V> VertexProperty<V> property(final String key, final V value) {
return this.property(key, value, EMPTY_ARGS);
}
/**
* Set the provided key to the provided value using default {@link VertexProperty.Cardinality} for that key.
* The default cardinality can be vendor defined and is usually tied to the graph schema.
* The default implementation of this method determines the cardinality
* {@code graph().features().vertex().getCardinality(key)}. The provided key/values are the properties of the
* newly created {@link VertexProperty}. These key/values must be provided in an even number where the odd
* numbered arguments are {@link String}.
*
* @param key the key of the vertex property
* @param value The value of the vertex property
* @param keyValues the key/value pairs to turn into vertex property properties
* @param <V> the type of the value of the vertex property
* @return the newly created vertex property
*/
public default <V> VertexProperty<V> property(final String key, final V value, final Object... keyValues) {
return this.property(graph().features().vertex().getCardinality(key), key, value, keyValues);
}
/**
* Create a new vertex property. If the cardinality is {@link VertexProperty.Cardinality#single}, then set the key
* to the value. If the cardinality is {@link VertexProperty.Cardinality#list}, then add a new value to the key.
* If the cardinality is {@link VertexProperty.Cardinality#set}, then only add a new value if that value doesn't
* already exist for the key. If the value already exists for the key, add the provided key value vertex property
* properties to it.
*
* @param cardinality the desired cardinality of the property key
* @param key the key of the vertex property
* @param value The value of the vertex property
* @param keyValues the key/value pairs to turn into vertex property properties
* @param <V> the type of the value of the vertex property
* @return the newly created vertex property
*/
public <V> VertexProperty<V> property(final VertexProperty.Cardinality cardinality, final String key, final V value, final Object... keyValues);
/**
* Gets an {@link Iterator} of incident edges.
*
* @param direction The incident direction of the edges to retrieve off this vertex
* @param edgeLabels The labels of the edges to retrieve. If no labels are provided, then get all edges.
* @return An iterator of edges meeting the provided specification
*/
public Iterator<Edge> edges(final Direction direction, final String... edgeLabels);
/**
* Gets an {@link Iterator} of adjacent vertices.
*
* @param direction The adjacency direction of the vertices to retrieve off this vertex
* @param edgeLabels The labels of the edges associated with the vertices to retrieve. If no labels are provided,
* then get all edges.
* @return An iterator of vertices meeting the provided specification
*/
public Iterator<Vertex> vertices(final Direction direction, final String... edgeLabels);
/**
* {@inheritDoc}
*/
@Override
public <V> Iterator<VertexProperty<V>> properties(final String... propertyKeys);
/**
* Common exceptions to use with a vertex.
*/
public static class Exceptions {
private Exceptions() {
}
public static UnsupportedOperationException userSuppliedIdsNotSupported() {
return new UnsupportedOperationException("Vertex does not support user supplied identifiers");
}
public static UnsupportedOperationException userSuppliedIdsOfThisTypeNotSupported() {
return new UnsupportedOperationException("Vertex does not support user supplied identifiers of this type");
}
public static IllegalStateException vertexRemovalNotSupported() {
return new IllegalStateException("Vertex removal are not supported");
}
public static IllegalStateException edgeAdditionsNotSupported() {
return new IllegalStateException("Edge additions not supported");
}
public static IllegalStateException multiplePropertiesExistForProvidedKey(final String propertyKey) {
return new IllegalStateException("Multiple properties exist for the provided key, use Vertex.properties(" + propertyKey + ')');
}
}
}