You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2015/04/29 16:54:29 UTC
incubator-tinkerpop git commit: Add some javadoc to
GraphReader/Writer and GraphSON implementations.
Repository: incubator-tinkerpop
Updated Branches:
refs/heads/master a8b0a2a54 -> a06067899
Add some javadoc to GraphReader/Writer and GraphSON implementations.
Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/a0606789
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/a0606789
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/a0606789
Branch: refs/heads/master
Commit: a060678991c8b1e185334c7ab3086c7258603d1b
Parents: a8b0a2a
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Wed Apr 29 10:53:58 2015 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Wed Apr 29 10:53:58 2015 -0400
----------------------------------------------------------------------
.../gremlin/structure/io/GraphReader.java | 13 +++-
.../gremlin/structure/io/GraphWriter.java | 25 ++++++-
.../structure/io/graphson/GraphSONReader.java | 18 +++++
.../structure/io/graphson/GraphSONWriter.java | 74 +++++++++++++++-----
4 files changed, 110 insertions(+), 20 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/a0606789/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphReader.java
----------------------------------------------------------------------
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphReader.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphReader.java
index 5682c19..3a57e58 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphReader.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphReader.java
@@ -31,7 +31,17 @@ import java.util.Iterator;
import java.util.function.Function;
/**
- * Functions for reading a graph and its graph elements from a different format.
+ * 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.
+ * <br/>
+ * 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)
*/
@@ -43,6 +53,7 @@ public interface GraphReader {
* the documentation of an implementation to understand the approach it takes.
*
* @param inputStream a stream containing a single vertex as defined by the accompanying {@link GraphWriter}
+ * @param graphToWriteTo the graph to write to when reading from the stream.
*/
public void readGraph(final InputStream inputStream, final Graph graphToWriteTo) throws IOException;
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/a0606789/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphWriter.java
----------------------------------------------------------------------
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphWriter.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphWriter.java
index a7d7c85..cee6968 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphWriter.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/GraphWriter.java
@@ -26,17 +26,33 @@ import org.apache.tinkerpop.gremlin.structure.Vertex;
import java.io.FileOutputStream;
import java.io.IOException;
+import java.io.InputStream;
import java.io.OutputStream;
import java.util.Iterator;
/**
- * Functions for writing a graph and its elements to a different format.
+ * Functions for writing a graph and its elements to a serialized format. Implementations of this class do not need
+ * to explicitly guarantee that an object written with one method must have its format equivalent to another. In other
+ * words calling {@link #writeVertex(OutputStream, Vertex)}} need not have equivalent output to
+ * {@link #writeObject(OutputStream, Object)}. Nor does the representation of an {@link Edge} within the output of
+ * {@link #writeVertex(OutputStream, Vertex, Direction)} need to match the representation of that same
+ * {@link Edge} when provided to {@link #writeEdge(OutputStream, Edge)}. In other words, implementations are free
+ * to optimize as is possible for a specific serialization method.
+ * <br/>
+ * That said, it is however important that the complementary "read" operation in {@link GraphReader} be capable of
+ * reading the output of the writer. In other words, the output of {@link #writeObject(OutputStream, Object)}
+ * should always be readable by {@link GraphReader#readObject(InputStream, Class)} and the output of
+ * {@link #writeGraph(OutputStream, Graph)} should always be readable by
+ * {@link GraphReader#readGraph(InputStream, Graph)}.
*
* @author Stephen Mallette (http://stephen.genoprime.com)
*/
public interface GraphWriter {
/**
* Write the entire graph to a stream.
+ *
+ * @param outputStream The stream to write to.
+ * @param g The graph to write to stream.
*/
public void writeGraph(final OutputStream outputStream, final Graph g) throws IOException;
@@ -45,7 +61,7 @@ public interface GraphWriter {
*
* @param outputStream The stream to write to.
* @param v The vertex to write.
- * @param direction If direction is null then no edges are written.
+ * @param direction The direction of edges to write or null if no edges are to be written.
*/
public void writeVertex(final OutputStream outputStream, final Vertex v, final Direction direction) throws IOException;
@@ -64,7 +80,7 @@ public interface GraphWriter {
*
* @param outputStream The stream to write to.
* @param vertexIterator A traversal that returns a list of vertices.
- * @param direction If direction is null then no edges are written.
+ * @param direction The direction of edges to write or null if no edges are to be written.
*/
public default void writeVertices(final OutputStream outputStream, final Iterator<Vertex> vertexIterator, final Direction direction) throws IOException {
while (vertexIterator.hasNext()) {
@@ -86,6 +102,9 @@ public interface GraphWriter {
/**
* Write an edge to a stream.
+ *
+ * @param outputStream The stream to write to.
+ * @param e The edge to write.
*/
public void writeEdge(final OutputStream outputStream, final Edge e) throws IOException;
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/a0606789/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONReader.java
----------------------------------------------------------------------
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONReader.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONReader.java
index b25c32b..7c0ebf1 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONReader.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONReader.java
@@ -67,6 +67,9 @@ public class GraphSONReader implements GraphReader {
this.batchSize = batchSize;
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public void readGraph(final InputStream inputStream, final Graph graphToWriteTo) throws IOException {
// dual pass - create all vertices and store to cache the ids. then create edges. as long as we don't
@@ -90,6 +93,9 @@ public class GraphSONReader implements GraphReader {
if (supportsTx) graphToWriteTo.tx().commit();
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public Iterator<Vertex> readVertices(final InputStream inputStream,
final Function<Attachable<Vertex>, Vertex> vertexAttachMethod,
@@ -99,11 +105,17 @@ public class GraphSONReader implements GraphReader {
return br.lines().<Vertex>map(FunctionUtils.wrapFunction(line -> readVertex(new ByteArrayInputStream(line.getBytes()), vertexAttachMethod, edgeAttachMethod, attachEdgesOfThisDirection))).iterator();
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public Vertex readVertex(final InputStream inputStream, final Function<Attachable<Vertex>, Vertex> vertexAttachMethod) throws IOException {
return readVertex(inputStream, vertexAttachMethod, null, null);
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public Vertex readVertex(final InputStream inputStream,
final Function<Attachable<Vertex>, Vertex> vertexAttachMethod,
@@ -122,6 +134,9 @@ public class GraphSONReader implements GraphReader {
return starGraph.getStarVertex();
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public Edge readEdge(final InputStream inputStream, final Function<Attachable<Edge>, Edge> edgeAttachMethod) throws IOException {
final Map<String, Object> edgeData = mapper.readValue(inputStream, mapTypeReference);
@@ -137,6 +152,9 @@ public class GraphSONReader implements GraphReader {
return edgeAttachMethod.apply(edge);
}
+ /**
+ * {@inheritDoc}
+ */
@Override
public <C> C readObject(final InputStream inputStream, final Class<? extends C> clazz) throws IOException {
return mapper.readValue(inputStream, clazz);
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/a0606789/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONWriter.java
----------------------------------------------------------------------
diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONWriter.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONWriter.java
index 07d28fc..5f9b879 100644
--- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONWriter.java
+++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/io/graphson/GraphSONWriter.java
@@ -47,26 +47,48 @@ public class GraphSONWriter implements GraphWriter {
this.mapper = mapper.createMapper();
}
+ /**
+ * Writes a {@link Graph} to stream in an adjacency list format where vertices are written with edges from both
+ * directions. Under this serialization model, edges are grouped by label.
+ *
+ * @param outputStream The stream to write to.
+ * @param g The graph to write to stream.
+ */
@Override
public void writeGraph(final OutputStream outputStream, final Graph g) throws IOException {
writeVertices(outputStream, g.vertices(), Direction.BOTH);
}
+ /**
+ * Writes a single {@link Vertex} to stream where edges only from the specified direction are written.
+ * Under this serialization model, edges are grouped by label.
+ *
+ * @param direction the direction of edges to write or null if no edges are to be written.
+ */
@Override
public void writeVertex(final OutputStream outputStream, final Vertex v, final Direction direction) throws IOException {
mapper.writeValue(outputStream, new StarGraphGraphSONSerializer.DirectionalStarGraph(StarGraph.of(v), direction));
}
+ /**
+ * Writes a single {@link Vertex} with no edges serialized.
+ *
+ * @param outputStream The stream to write to.
+ * @param v The vertex to write.
+ */
@Override
public void writeVertex(final OutputStream outputStream, final Vertex v) throws IOException {
- mapper.writeValue(outputStream, new StarGraphGraphSONSerializer.DirectionalStarGraph(StarGraph.of(v), null));
- }
-
- @Override
- public void writeEdge(final OutputStream outputStream, final Edge e) throws IOException {
- mapper.writeValue(outputStream, e);
+ writeVertex(outputStream, v, null);
}
+ /**
+ * Writes a list of vertices in adjacency list format where vertices are written with edges from both
+ * directions. Under this serialization model, edges are grouped by label.
+ *
+ * @param outputStream The stream to write to.
+ * @param vertexIterator A traversal that returns a list of vertices.
+ * @param direction If direction is null then no edges are written.
+ */
@Override
public void writeVertices(final OutputStream outputStream, final Iterator<Vertex> vertexIterator, final Direction direction) throws IOException {
final BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream));
@@ -82,21 +104,41 @@ public class GraphSONWriter implements GraphWriter {
writer.flush();
}
+ /**
+ * Writes a list of vertices without edges.
+ *
+ * @param outputStream The stream to write to.
+ * @param vertexIterator A iterator that returns a list of vertices.
+ */
@Override
public void writeVertices(final OutputStream outputStream, final Iterator<Vertex> vertexIterator) throws IOException {
- final BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream));
- try (final ByteArrayOutputStream baos = new ByteArrayOutputStream()) {
- while (vertexIterator.hasNext()) {
- writeVertex(baos, vertexIterator.next());
- writer.write(new String(baos.toByteArray()));
- writer.newLine();
- baos.reset();
- }
- }
+ writeVertices(outputStream, vertexIterator, null);
+ }
- writer.flush();
+ /**
+ * Writes an {@link Edge} object to the stream. Note that this format is different from the format of an
+ * {@link Edge} when serialized with a {@link Vertex} as done with
+ * {@link #writeVertex(OutputStream, Vertex, Direction)} or
+ * {@link #writeVertices(OutputStream, Iterator, Direction)} in that the edge label is part of the object and
+ * vertex labels are included with their identifiers.
+ *
+ * @param outputStream The stream to write to.
+ * @param e The edge to write.
+ */
+ @Override
+ public void writeEdge(final OutputStream outputStream, final Edge e) throws IOException {
+ mapper.writeValue(outputStream, e);
}
+ /**
+ * Writes an arbitrary object to the stream. Note that Gremlin Server uses this method when serializing output,
+ * thus the format of the GraphSON for a {@link Vertex} will be somewhat different from the format supplied
+ * when using {@link #writeVertex(OutputStream, Vertex, Direction)}. For example, edges will never be included.
+ *
+ * @param outputStream The stream to write to
+ * @param object The object to write which will use the standard serializer set
+ * @throws IOException
+ */
@Override
public void writeObject(final OutputStream outputStream, final Object object) throws IOException {
this.mapper.writeValue(outputStream, object);