TINKERPOP-3154 Added docs/tests for subgraph() CTR

Author: spmallette

docs/src/reference/gremlin-variants.asciidoc

@@ -860,6 +860,24 @@ ensure compatibility when making requests. Obviously, it is possible to switch t
 the appropriate `MessageSerializer` (e.g. `GraphSONMessageSerializerV3` or `GraphBinaryMessageSerializerV1` respectively)
 in the same way and building that into the `Cluster` object.
 
+A particularly important configuration along these lines is easily overlooked when choosing to use GraphSON rather than
+GraphBinary. GraphBinary offers a bit of help in dynamically detecting available classpath items and will dynamically
+include `TinkerGraph` as a serialization target which allows the <<subgraph-step>> to work properly in remote contexts.
+GraphSON does not. When using GraphSON, you must manually include the `TinkerIoRegistryV3` in the configuration for the
+driver.
+
+[source,java]
+----
+GraphSONMapper.Builder builder = GraphSONMapper.build().addRegistry(TinkerIoRegistryV3.instance());
+GraphSONMessageSerializerV3 serializer = new GraphSONMessageSerializerV3(builder);
+Cluster cluster = TestClientFactory.build().serializer(serializer).create();
+Client client = cluster.connect();
+GraphTraversalSource g = traversal().withRemote(DriverRemoteConnection.using(client, "g"));
+----
+
+IMPORTANT: Prefer GraphBinary over GraphSON when using the driver. If you do choose GraphSON, prefer GraphSON 3 and
+know that GraphSON 2 is not compatible with <<subgraph-step>.
+
 [[gremlin-java-lambda]]
 === The Lambda Solution
 

gremlin-server/src/test/java/org/apache/tinkerpop/gremlin/server/GremlinDriverIntegrateTest.java

@@ -23,6 +23,11 @@
 import nl.altindag.log.LogCaptor;
 import org.apache.tinkerpop.gremlin.driver.Channelizer;
 import org.apache.tinkerpop.gremlin.server.channel.HttpChannelizer;
+import org.apache.tinkerpop.gremlin.structure.Graph;
+import org.apache.tinkerpop.gremlin.structure.io.Mapper;
+import org.apache.tinkerpop.gremlin.structure.io.graphson.GraphSONMapper;
+import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV2;
+import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerIoRegistryV3;
 import org.apache.tinkerpop.gremlin.util.ExceptionHelper;
 import org.apache.tinkerpop.gremlin.TestHelper;
 import org.apache.tinkerpop.gremlin.driver.Client;
@@ -39,6 +44,8 @@
 import org.apache.tinkerpop.gremlin.util.message.ResponseStatusCode;
 import org.apache.tinkerpop.gremlin.driver.remote.DriverRemoteConnection;
 import org.apache.tinkerpop.gremlin.util.ser.GraphBinaryMessageSerializerV1;
+import org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV2;
+import org.apache.tinkerpop.gremlin.util.ser.GraphSONMessageSerializerV3;
 import org.apache.tinkerpop.gremlin.util.ser.Serializers;
 import org.apache.tinkerpop.gremlin.jsr223.ScriptFileGremlinPlugin;
 import org.apache.tinkerpop.gremlin.process.traversal.Bytecode;
@@ -209,6 +216,46 @@ public Settings overrideSettings(final Settings settings) {
         return settings;
     }
 
+    @Test
+    public void shouldSubgraphWithGraphSONV3Serialization() throws Exception {
+        // validating subgraph() serialization here b/c we don't have feature tests for it yet in gherkin
+        final GraphSONMapper.Builder builder = GraphSONMapper.build().addRegistry(TinkerIoRegistryV3.instance());
+        final GraphSONMessageSerializerV3 serializer = new GraphSONMessageSerializerV3(builder);
+        final Cluster cluster = TestClientFactory.build().serializer(serializer).create();
+        final Client client = cluster.connect();
+
+        try {
+            final List<Result> r = client.submit("TinkerFactory.createModern().traversal().E().hasLabel('knows').subgraph('x').cap('x')").all().join();
+            assertEquals(1, r.size());
+
+            final Graph graph = r.get(0).get(Graph.class);
+            final GraphTraversalSource g = traversal().withEmbedded(graph);
+            assertEquals(2, g.E().count().next().longValue());
+            assertEquals(3, g.V().count().next().longValue());
+        } finally {
+            cluster.close();
+        }
+    }
+
+    @Test
+    public void shouldSubgraphWithGraphBinaryV1Serialization() throws Exception {
+        // validating subgraph() serialization here b/c we don't have feature tests for it yet in gherkin
+        final Cluster cluster = TestClientFactory.build().serializer(Serializers.GRAPHBINARY_V1).create();
+        final Client client = cluster.connect();
+
+        try {
+            final List<Result> r = client.submit("TinkerFactory.createModern().traversal().E().hasLabel('knows').subgraph('x').cap('x')").all().join();
+            assertEquals(1, r.size());
+
+            final Graph graph = r.get(0).get(Graph.class);
+            final GraphTraversalSource g = traversal().withEmbedded(graph);
+            assertEquals(2, g.E().count().next().longValue());
+            assertEquals(3, g.V().count().next().longValue());
+        } finally {
+            cluster.close();
+        }
+    }
+
     @Test
     public void shouldInterceptRequests() throws Exception {
         final int requestsToMake = 32;