/*
* 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.io;
import org.apache.tinkerpop.gremlin.process.computer.GraphFilter;
import org.apache.tinkerpop.gremlin.structure.Direction;
import org.apache.tinkerpop.gremlin.structure.Edge;
import org.apache.tinkerpop.gremlin.structure.Graph;
import org.apache.tinkerpop.gremlin.structure.Property;
import org.apache.tinkerpop.gremlin.structure.Vertex;
import org.apache.tinkerpop.gremlin.structure.VertexProperty;
import org.apache.tinkerpop.gremlin.structure.util.Attachable;
import org.apache.tinkerpop.gremlin.structure.util.Host;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.util.Iterator;
import java.util.Optional;
import java.util.function.Function;
/**
* Functions for reading a graph and its graph elements from a different serialization format. Implementations of
* this class do not need to explicitly guarantee that an object read with one method must have its format
* equivalent to another. In other words the input to {@link #readVertex(InputStream, Function)}} need not also
* be readable by {@link #readObject(InputStream, Class)}. In other words, implementations are free
* to optimize as is possible for a specific serialization method.
* <p/>
* That said, it is however important that the complementary "write" operation in {@link GraphWriter} be capable of
* writing output compatible to its reader. In other words, the output of
* {@link GraphWriter#writeObject(OutputStream, Object)} should always be readable by
* {@link #readObject(InputStream, Class)} and the output of {@link GraphWriter#writeGraph(OutputStream, Graph)}
* should always be readable by {@link #readGraph(InputStream, Graph)}.
*
* @author Stephen Mallette (http://stephen.genoprime.com)
*/
public interface GraphReader {
/**
* Reads an entire graph from an {@link InputStream}. This method is mean to load an empty {@link Graph}.
* It is up to individual implementations to manage transactions, but it is not required or enforced. Consult
* the documentation of an implementation to understand the approach it takes.
*
* @param inputStream a stream containing an entire graph of vertices and edges as defined by the accompanying
* {@link GraphWriter#writeGraph(OutputStream, Graph)}.
* @param graphToWriteTo the graph to write to when reading from the stream.
*/
public void readGraph(final InputStream inputStream, final Graph graphToWriteTo) throws IOException;
/**
* Reads a single vertex from an {@link InputStream}. This method will filter the read the read vertex by the provided
* {@link GraphFilter}. If the graph filter will filter the vertex itself, then the returned {@link Optional} is empty.
*
* @param inputStream a stream containing at least a single vertex as defined by the accompanying
* {@link GraphWriter#writeVertex(OutputStream, Vertex)}.
* @param graphFilter The {@link GraphFilter} to filter the vertex and its associated edges by.
* @return the vertex with filtered edges or {@link Optional#empty()} if the vertex itself was filtered.
* @throws IOException
*/
public default Optional<Vertex> readVertex(final InputStream inputStream, final GraphFilter graphFilter) throws IOException {
throw new UnsupportedOperationException(this.getClass().getCanonicalName() + " currently does not support " + GraphFilter.class.getSimpleName() + " deserialization filtering");
}
/**
* Reads a single vertex from an {@link InputStream}. This method will read vertex properties but not edges.
* It is expected that the user will manager their own transaction context with respect to this method (i.e.
* implementations should not commit the transaction for the user).
*
* @param inputStream a stream containing at least a single vertex as defined by the accompanying
* {@link GraphWriter#writeVertex(OutputStream, Vertex)}.
* @param vertexAttachMethod a function that creates re-attaches a {@link Vertex} to a {@link Host} object.
*/
public Vertex readVertex(final InputStream inputStream, final Function<Attachable<Vertex>, Vertex> vertexAttachMethod) throws IOException;
/**
* Reads a single vertex from an {@link InputStream}. This method will read vertex properties as well as edges
* given the direction supplied as an argument. It is expected that the user will manager their own transaction
* context with respect to this method (i.e. implementations should not commit the transaction for the user).
*
* @param inputStream a stream containing at least one {@link Vertex} as defined by the accompanying
* {@link GraphWriter#writeVertices(OutputStream, Iterator, Direction)} method.
* @param vertexAttachMethod a function that creates re-attaches a {@link Vertex} to a {@link Host} object.
* @param edgeAttachMethod a function that creates re-attaches a {@link Edge} to a {@link Host} object.
* @param attachEdgesOfThisDirection only edges of this direction are passed to the {@code edgeMaker}.
*/
public Vertex readVertex(final InputStream inputStream,
final Function<Attachable<Vertex>, Vertex> vertexAttachMethod,
final Function<Attachable<Edge>, Edge> edgeAttachMethod,
final Direction attachEdgesOfThisDirection) throws IOException;
/**
* Reads a set of one or more vertices from an {@link InputStream} which were written by
* {@link GraphWriter#writeVertices(OutputStream, Iterator)}. This method will read vertex properties as well as
* edges given the direction supplied as an argument. It is expected that the user will manager their own
* transaction context with respect to this method (i.e. implementations should not commit the transaction for
* the user).
*
* @param inputStream a stream containing at least one {@link Vertex} as defined by the accompanying
* {@link GraphWriter#writeVertices(OutputStream, Iterator, Direction)} or
* {@link GraphWriter#writeVertices(OutputStream, Iterator)} methods.
* @param vertexAttachMethod a function that creates re-attaches a {@link Vertex} to a {@link Host} object.
* @param edgeAttachMethod a function that creates re-attaches a {@link Edge} to a {@link Host} object.
* @param attachEdgesOfThisDirection only edges of this direction are passed to the {@code edgeMaker}.
*/
public Iterator<Vertex> readVertices(final InputStream inputStream,
final Function<Attachable<Vertex>, Vertex> vertexAttachMethod,
final Function<Attachable<Edge>, Edge> edgeAttachMethod,
final Direction attachEdgesOfThisDirection) throws IOException;
/**
* Reads a single edge from an {@link InputStream}. It is expected that the user will manager their own
* transaction context with respect to this method (i.e. implementations should not commit the transaction for
* the user).
*
* @param inputStream a stream containing at least one {@link Edge} as defined by the accompanying
* {@link GraphWriter#writeEdge(OutputStream, Edge)} method.
* @param edgeAttachMethod a function that creates re-attaches a {@link Edge} to a {@link Host} object.
*/
public Edge readEdge(final InputStream inputStream, final Function<Attachable<Edge>, Edge> edgeAttachMethod) throws IOException;
/**
* Reads a single vertex property from an {@link InputStream}. It is expected that the user will manager their own
* transaction context with respect to this method (i.e. implementations should not commit the transaction for
* the user).
*
* @param inputStream a stream containing at least one {@link VertexProperty} as written by the accompanying
* {@link GraphWriter#writeVertexProperty(OutputStream, VertexProperty)} method.
* @param vertexPropertyAttachMethod a function that creates re-attaches a {@link VertexProperty} to a
* {@link Host} object.
* @return the value returned by the attach method.
*/
public VertexProperty readVertexProperty(final InputStream inputStream,
final Function<Attachable<VertexProperty>, VertexProperty> vertexPropertyAttachMethod) throws IOException;
/**
* Reads a single property from an {@link InputStream}. It is expected that the user will manager their own
* transaction context with respect to this method (i.e. implementations should not commit the transaction for
* the user).
*
* @param inputStream a stream containing at least one {@link Property} as written by the accompanying
* {@link GraphWriter#writeProperty(OutputStream, Property)} method.
* @param propertyAttachMethod a function that creates re-attaches a {@link Property} to a {@link Host} object.
* @return the value returned by the attach method.
*/
public Property readProperty(final InputStream inputStream,
final Function<Attachable<Property>, Property> propertyAttachMethod) throws IOException;
/**
* Reads an arbitrary object using the registered serializers.
*
* @param inputStream a stream containing an object.
* @param clazz the class expected to be in the stream - may or may not be used by the underlying implementation.
*/
public <C> C readObject(final InputStream inputStream, final Class<? extends C> clazz) throws IOException;
/**
* Largely a marker interface for builder classes that construct a {@link GraphReader}.
*/
public interface ReaderBuilder<T extends GraphReader> {
/**
* Creates the {@link GraphReader} implementation given options provided to the {@link ReaderBuilder}
* implementation.
*/
T create();
}
}