Update javadocs and other minor refactoring in remoting.
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/8dd02119 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/8dd02119 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/8dd02119 Branch: refs/heads/TINKERPOP-1278 Commit: 8dd021192d0b564eb282a0741cdbdc601a863efe Parents: 39233fc Author: Stephen Mallette <sp...@genoprime.com> Authored: Fri Jul 29 16:43:55 2016 -0400 Committer: Stephen Mallette <sp...@genoprime.com> Committed: Fri Jul 29 16:43:55 2016 -0400 ---------------------------------------------------------------------- .../process/remote/RemoteConnection.java | 10 ++++++++-- .../gremlin/process/remote/RemoteResponse.java | 20 ++++++++++++++++++++ .../traversal/step/util/BulkedResult.java | 8 ++++---- .../structure/io/gryo/GryoMapperTest.java | 2 +- .../driver/remote/DriverRemoteResponse.java | 11 ++++++++--- .../remote/DriverTraversalSideEffects.java | 14 ++++---------- 6 files changed, 45 insertions(+), 20 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/8dd02119/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteConnection.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteConnection.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteConnection.java index 9efc9b8..870bed4 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteConnection.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteConnection.java @@ -26,7 +26,9 @@ import java.util.Iterator; /** * A simple abstraction of a "connection" to a "server" that is capable of processing a {@link Traversal} and - * returning an {@link Iterator} of {@link Traverser} results. + * returning results. Results refer to both the {@link Iterator} of results from the submitted {@link Traversal} + * as well as the side-effects produced by that {@link Traversal}. Those results together are wrapped in a + * {@link RemoteResponse}. * * @author Stephen Mallette (http://stephen.genoprime.com) * @author Marko A. Rodriguez (http://markorodriguez.com) @@ -39,6 +41,10 @@ public interface RemoteConnection extends AutoCloseable { @Deprecated public <E> Iterator<Traverser.Admin<E>> submit(final Traversal<?, E> traversal) throws RemoteConnectionException; - + /** + * Submits {@link Traversal} {@link Bytecode} to a server and returns a {@link RemoteResponse}. + * The {@link RemoteResponse} is an abstraction over two types of results that can be returned as part of the + * response from the server: the results of the {@link Traversal} itself and the the side-effects that it produced. + */ public <E> RemoteResponse<E> submit(final Bytecode bytecode) throws RemoteConnectionException; } http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/8dd02119/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteResponse.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteResponse.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteResponse.java index 8d2e13c..d2d7be6 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteResponse.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/RemoteResponse.java @@ -18,17 +18,37 @@ */ package org.apache.tinkerpop.gremlin.process.remote; +import org.apache.tinkerpop.gremlin.process.remote.traversal.RemoteTraverser; +import org.apache.tinkerpop.gremlin.process.traversal.Bytecode; +import org.apache.tinkerpop.gremlin.process.traversal.Traversal; import org.apache.tinkerpop.gremlin.process.traversal.TraversalSideEffects; import org.apache.tinkerpop.gremlin.process.traversal.Traverser; +import org.apache.tinkerpop.gremlin.process.traversal.util.DefaultTraversalSideEffects; import java.util.Iterator; /** + * The {@code RemoteResponse} is returned from {@link RemoteConnection#submit(Bytecode)} and provides implementers a + * way to represent how they will return the results of a submitted {@link Traversal} and its side-effects. The + * {@code RemoteResponse} is used internally by traversals spawned from a {@link RemoteGraph} to put remote results + * into the streams of those traversals and to replace client-side {@link TraversalSideEffects} in those traversals. + * * @author Stephen Mallette (http://stephen.genoprime.com) */ public interface RemoteResponse<E> { + /** + * Gets the list of results from a {@link Traversal} executed remotely. Implementers may push their results into + * a {@link RemoteTraverser} instance to feed that {@code Iterator} or create their own implementation of it if + * there is some advantage to doing so. + */ public Iterator<Traverser.Admin<E>> getResult(); + /** + * Gets the side-effects (if any) from the remotely executed {@link Traversal}. Simple implementations could + * likely use {@link DefaultTraversalSideEffects}, but more advanced implementations might look to lazily load + * side-effects or otherwise implement some form of blocking to ensure that all side-effects are present from the + * remote location. + */ public TraversalSideEffects getSideEffects(); } http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/8dd02119/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/traversal/step/util/BulkedResult.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/traversal/step/util/BulkedResult.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/traversal/step/util/BulkedResult.java index 56abf4b..1a4eaa9 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/traversal/step/util/BulkedResult.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/remote/traversal/step/util/BulkedResult.java @@ -23,16 +23,16 @@ package org.apache.tinkerpop.gremlin.process.remote.traversal.step.util; * * @author Stephen Mallette (http://stephen.genoprime.com) */ -public class BulkedResult { - private final Object result; +public class BulkedResult<T> { + private final T result; private final long bulk; - public BulkedResult(final Object result, final long bulk) { + public BulkedResult(final T result, final long bulk) { this.result = result; this.bulk = bulk; } - public Object getResult() { + public T getResult() { return result; } http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/8dd02119/gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoMapperTest.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoMapperTest.java b/gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoMapperTest.java index ce737ec..4c06800 100644 --- a/gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoMapperTest.java +++ b/gremlin-core/src/test/java/org/apache/tinkerpop/gremlin/structure/io/gryo/GryoMapperTest.java @@ -242,7 +242,7 @@ public class GryoMapperTest { @Test public void shouldHandleBulkedResult() throws Exception { - final BulkedResult br = new BulkedResult(123, 1000); + final BulkedResult<Integer> br = new BulkedResult<>(123, 1000); final BulkedResult inOut = serializeDeserialize(br, BulkedResult.class); assertEquals(br.getBulk(), inOut.getBulk()); assertEquals(br.getResult(), inOut.getResult()); http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/8dd02119/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverRemoteResponse.java ---------------------------------------------------------------------- diff --git a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverRemoteResponse.java b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverRemoteResponse.java index 9697053..264a2cc 100644 --- a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverRemoteResponse.java +++ b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverRemoteResponse.java @@ -36,6 +36,8 @@ import java.util.Optional; import java.util.function.Supplier; /** + * A {@link RemoteResponse} implementation for the Gremlin Driver. + * * @author Stephen Mallette (http://stephen.genoprime.com) */ public class DriverRemoteResponse<E> implements RemoteResponse<E> { @@ -44,6 +46,9 @@ public class DriverRemoteResponse<E> implements RemoteResponse<E> { private final TraversalSideEffects sideEffects; public DriverRemoteResponse(final ResultSet rs, final boolean attach, Optional<Configuration> conf) { + // attaching is really just for testing purposes. it doesn't make sense in any real-world scenario as it would + // require that the client have access to the Graph instance that produced the result. tests need that + // attachment process to properly execute in full hence this little hack. if (attach) { if (!conf.isPresent()) throw new IllegalStateException("Traverser can't be reattached for testing"); final Graph graph = ((Supplier<Graph>) conf.get().getProperty("hidden.for.testing.only")).get(); @@ -67,7 +72,7 @@ public class DriverRemoteResponse<E> implements RemoteResponse<E> { static class TraverserIterator<E> implements Iterator<Traverser.Admin<E>> { - private Iterator<Result> inner; + private final Iterator<Result> inner; public TraverserIterator(final Iterator<Result> resultIterator) { inner = resultIterator; @@ -80,8 +85,8 @@ public class DriverRemoteResponse<E> implements RemoteResponse<E> { @Override public Traverser.Admin<E> next() { - final BulkedResult br = (BulkedResult) inner.next().getObject(); - return new RemoteTraverser<>((E) br.getResult(), br.getBulk()); + final BulkedResult<E> br = (BulkedResult) inner.next().getObject(); + return new RemoteTraverser<>(br.getResult(), br.getBulk()); } } http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/8dd02119/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverTraversalSideEffects.java ---------------------------------------------------------------------- diff --git a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverTraversalSideEffects.java b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverTraversalSideEffects.java index 328897a..6996df4 100644 --- a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverTraversalSideEffects.java +++ b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/remote/DriverTraversalSideEffects.java @@ -19,19 +19,13 @@ package org.apache.tinkerpop.gremlin.driver.remote; import org.apache.tinkerpop.gremlin.driver.ResultSet; -import org.apache.tinkerpop.gremlin.process.remote.traversal.step.util.BulkedResult; import org.apache.tinkerpop.gremlin.process.traversal.TraversalSideEffects; -import org.apache.tinkerpop.gremlin.process.traversal.step.util.BulkSet; -import org.apache.tinkerpop.gremlin.process.traversal.util.DefaultTraversalSideEffects; import org.apache.tinkerpop.gremlin.structure.util.StringFactory; -import java.util.List; import java.util.Map; import java.util.Optional; import java.util.Set; import java.util.concurrent.CompletableFuture; -import java.util.concurrent.ExecutionException; -import java.util.concurrent.atomic.AtomicReference; import java.util.function.BinaryOperator; import java.util.function.Supplier; import java.util.function.UnaryOperator; @@ -48,10 +42,6 @@ public class DriverTraversalSideEffects implements TraversalSideEffects { this.rs = rs; } - private synchronized void initializeFuture() { - if (null == future) future = rs.getSideEffectResults(); - } - @Override public <V> V get(final String key) throws IllegalArgumentException { initializeFuture(); @@ -153,4 +143,8 @@ public class DriverTraversalSideEffects implements TraversalSideEffects { public String toString() { return StringFactory.traversalSideEffectsString(this); } + + private synchronized void initializeFuture() { + if (null == future) future = rs.getSideEffectResults(); + } }
