[GitHub] [tinkerpop] divijvaidya commented on issue #1110: TINKERPOP-2211 Add API which allows per-request option for bytecode
divijvaidya commented on issue #1110: TINKERPOP-2211 Add API which allows per-request option for bytecode URL: https://github.com/apache/tinkerpop/pull/1110#issuecomment-490737742 While we are around this code base, can we also add request ID as part of the request options as well. VOTE +1 : Code is OK, Semantics of this change is OK This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[tinkerpop] branch TINKERPOP-2199 updated (e974db3 -> 52159f6)
This is an automated email from the ASF dual-hosted git repository. spmallette pushed a change to branch TINKERPOP-2199 in repository https://gitbox.apache.org/repos/asf/tinkerpop.git. discard e974db3 TINKERPOP-2199 Added some more java tests for within()/without() for GraphSON discard 9ed9afb TINKERPOP-2199 Fixed the bad GraphSON 3.0 docs for within() and without() discard 9af53c5 TINKERPOP-2199 P.within()/without() behaves more consistently for .NET discard 7abc8b8 TINKERPOP-2199 Fixed P.within()/without() behavior in gremlin-python add 30b2535 TINKERPOP-2208 Added inject() to steps geneerated by the DSL TraversalSource CTR add 6a25284 TINKERPOP-2204 Prevent client-side hangs if server metadata generation fails CTR add 734b7b2 Create uber jar for gremlin-console add 5799ca5 Merge branch 'pr-1103' into uberjar add 6caeb93 Generated an uberjar artifact for Gremlin Console add 6d8560b Bump gmavenplus plugin to 1.7.0 CTR add 8456052 Add IO test data files for 3.3.7 CTR add df124b1 Cleared the input buffer after exceptions in Gremlin Console CTR add 8ad4f60 Fixed mispelling in changelog CTR add beae963 Fixed text formatting CTR add 7190091 TINKERPOP-2199 Fixed P.within()/without() behavior in gremlin-python add ef41dca TINKERPOP-2199 P.within()/without() behaves more consistently for .NET add 2e5a70b TINKERPOP-2199 Fixed the bad GraphSON 3.0 docs for within() and without() add 52159f6 TINKERPOP-2199 Added some more java tests for within()/without() for GraphSON This update added new revisions after undoing existing revisions. That is to say, some revisions that were in the old version of the branch are not in the new version. This situation occurs when a user --force pushes a change and generates a repository containing something like this: * -- * -- B -- O -- O -- O (e974db3) \ N -- N -- N refs/heads/TINKERPOP-2199 (52159f6) You should already have received notification emails for all of the O revisions, and so the following emails describe only the N revisions from the common base, B. Any revisions marked "omit" are not gone; other references still refer to them. Any revisions marked "discard" are gone forever. No new revisions were added by this update. Summary of changes: CHANGELOG.asciidoc | 4 + .../dev/developer/development-environment.asciidoc | 2 +- docs/src/dev/developer/for-committers.asciidoc | 9 ++- gremlin-console/pom.xml| 83 + .../tinkerpop/gremlin/console/Console.groovy | 2 + .../process/traversal/dsl/GremlinDslProcessor.java | 14 .../server/op/traversal/TraversalOpProcessor.java | 3 +- .../io/graphson/GraphSONCompatibility.java | 6 +- .../structure/io/gryo/GryoCompatibility.java | 4 +- .../graphson/GraphSONTypedCompatibilityTest.java | 4 +- .../graphson/GraphSONUntypedCompatibilityTest.java | 4 +- .../structure/io/gryo/GryoCompatibilityTest.java | 4 +- .../authenticationchallenge-v1d0.json | 0 .../authenticationchallenge-v2d0-no-types.json | 0 .../authenticationchallenge-v2d0-partial.json | 0 .../authenticationchallenge-v3d0.json | 0 .../authenticationresponse-v1d0.json | 0 .../authenticationresponse-v2d0-no-types.json | 0 .../authenticationresponse-v2d0-partial.json | 0 .../authenticationresponse-v3d0.json | 0 .../{_3_3_6 => _3_3_7}/barrier-v2d0-partial.json | 0 .../graphson/{_3_3_6 => _3_3_7}/barrier-v3d0.json | 0 .../bigdecimal-v2d0-partial.json | 0 .../{_3_3_6 => _3_3_7}/bigdecimal-v3d0.json| 0 .../biginteger-v2d0-partial.json | 0 .../{_3_3_6 => _3_3_7}/biginteger-v3d0.json| 0 .../{_3_3_6 => _3_3_7}/binding-v2d0-partial.json | 0 .../graphson/{_3_3_6 => _3_3_7}/binding-v3d0.json | 0 .../{_3_3_6 => _3_3_7}/byte-v2d0-partial.json | 0 .../io/graphson/{_3_3_6 => _3_3_7}/byte-v3d0.json | 0 .../bytebuffer-v2d0-partial.json | 0 .../{_3_3_6 => _3_3_7}/bytebuffer-v3d0.json| 0 .../{_3_3_6 => _3_3_7}/bytecode-v2d0-partial.json | 0 .../graphson/{_3_3_6 => _3_3_7}/bytecode-v3d0.json | 0 .../cardinality-v2d0-partial.json | 0 .../{_3_3_6 => _3_3_7}/cardinality-v3d0.json | 0 .../{_3_3_6 => _3_3_7}/char-v2d0-partial.json | 0 .../io/graphson/{_3_3_6 => _3_3_7}/char-v3d0.json | 0 .../{_3_3_6 => _3_3_7}/class-v2d0-partial.json | 0 .../io/graphson/{_3_3_6 => _3_3_7}/class-v3d0.json | 0 .../{_3_3_6 => _3_3_7}/column-v2d0-partial.json| 0 .../graphson/{_3_3_6 => _3_3_7}/column-v3d0.json | 0 .../{_3_3_6 => _3_3_7}/date-v2d0-no-types.json | 0 .../{_3_3_6 => _3_3_7}/date-v2d0-partial.json | 0 .../io/graphson/{_3_3_6 =>
[tinkerpop] branch tp33 updated (8ad4f60 -> beae963)
This is an automated email from the ASF dual-hosted git repository. spmallette pushed a change to branch tp33 in repository https://gitbox.apache.org/repos/asf/tinkerpop.git. from 8ad4f60 Fixed mispelling in changelog CTR add beae963 Fixed text formatting CTR No new revisions were added by this update. Summary of changes: docs/src/dev/developer/development-environment.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
[tinkerpop] branch master updated: Fixed text formatting CTR
This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git The following commit(s) were added to refs/heads/master by this push: new beae963 Fixed text formatting CTR new 48e44b2 Merge branch 'tp33' beae963 is described below commit beae963e7a00c544dc8ca6a6e4b346e075eac27c Author: Stephen Mallette AuthorDate: Wed May 8 15:11:01 2019 -0400 Fixed text formatting CTR --- docs/src/dev/developer/development-environment.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/dev/developer/development-environment.asciidoc b/docs/src/dev/developer/development-environment.asciidoc index 28183d9..ec1c8d3 100644 --- a/docs/src/dev/developer/development-environment.asciidoc +++ b/docs/src/dev/developer/development-environment.asciidoc @@ -327,6 +327,6 @@ that: . `File | Settings | Compiler | Annotation Processors` has the checkbox with the "Enable annotation processing" checked. Intellij should be able to detect the processor automatically on build. . The `gremlin-core/target` directory should not be hidden and `target/classes`, `target/generated-sources` and -`target/generated-test-sources should be marked as "Generated Sources Root". If they are not setup that way by +`target/generated-test-sources` should be marked as "Generated Sources Root". If they are not setup that way by Intellij by default then simply right-click on them use the "Mark Directory with" option to make the appropriate selections.
[GitHub] [tinkerpop] spmallette closed pull request #1109: TINKERPOP-2211 Add API which allows per-request option for bytecode
spmallette closed pull request #1109: TINKERPOP-2211 Add API which allows per-request option for bytecode URL: https://github.com/apache/tinkerpop/pull/1109 This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[GitHub] [tinkerpop] spmallette commented on issue #1109: TINKERPOP-2211 Add API which allows per-request option for bytecode
spmallette commented on issue #1109: TINKERPOP-2211 Add API which allows per-request option for bytecode URL: https://github.com/apache/tinkerpop/pull/1109#issuecomment-490609291 I cherry-picked your the commit in this PR into the TINKERPOP-2211 branch and added the support for `with()`. It was easy enough and I even found a bug while doing it. :) I've opened a fresh PR at #1110 for review/VOTE and am now closing this one. Please have a look when you get a chance to make sure all is in order - thanks. This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[GitHub] [tinkerpop] spmallette opened a new pull request #1110: TINKERPOP-2211 Add API which allows per-request option for bytecode
spmallette opened a new pull request #1110: TINKERPOP-2211 Add API which allows per-request option for bytecode URL: https://github.com/apache/tinkerpop/pull/1110 https://issues.apache.org/jira/browse/TINKERPOP-2211 Support `RequestOptions` with the Java driver using `TraversalSource.with()`. This PR replaces #1109 ```text g = traversal().withRemote(...); g.with(PER_REQUEST_TIMEOUT, 500L).V().has(...).out(). ``` Builds with `mvn clean install && mvn verify -pl gremlin-server -DskipIntegrationTests=false` VOTE +1 This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[tinkerpop] branch TINKERPOP-2211 created (now bebd9e7)
This is an automated email from the ASF dual-hosted git repository. spmallette pushed a change to branch TINKERPOP-2211 in repository https://gitbox.apache.org/repos/asf/tinkerpop.git. at bebd9e7 TINKERPOP-2211 Added method to set RequestOptions using with() This branch includes the following new commits: new 138a4a9 TINKERPOP-2211 Add API to which allows per-request option for bytecode submission new bebd9e7 TINKERPOP-2211 Added method to set RequestOptions using with() The 2 revisions listed above as "new" are entirely new to this repository and will be described in separate emails. The revisions listed as "add" were already present in the repository and have only been added to this reference.
[tinkerpop] 01/02: TINKERPOP-2211 Add API to which allows per-request option for bytecode submission
This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch TINKERPOP-2211 in repository https://gitbox.apache.org/repos/asf/tinkerpop.git commit 138a4a9b49c696acb8ab2a348e4ccd712dca94b0 Author: Divij Vaidya AuthorDate: Mon May 6 21:09:16 2019 -0700 TINKERPOP-2211 Add API to which allows per-request option for bytecode submission --- .../apache/tinkerpop/gremlin/driver/Client.java| 48 +- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/Client.java b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/Client.java index 1df2d0d..16c3b76 100644 --- a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/Client.java +++ b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/Client.java @@ -151,6 +151,24 @@ public abstract class Client { } /** + * A version of {@link #submit(Bytecode)} which provides the ability to set per-request options. + * + * @param bytecode request in the form of gremlin {@link Bytecode} + * @param options for the request + * + * @see #submit(Bytecode) + */ +public ResultSet submit(final Bytecode bytecode, final RequestOptions options) { +try { +return submitAsync(bytecode, options).get(); +} catch (UnsupportedOperationException uoe) { +throw uoe; +} catch (Exception ex) { +throw new RuntimeException(ex); +} +} + +/** * An asynchronous version of {@link #submit(Traversal)}. Results are returned as {@link Traverser} instances and * are therefore bulked, meaning that to properly iterate the contents of the result each {@link Traverser#bulk()} * must be examined to determine the number of times that object should be presented in iteration. @@ -160,6 +178,18 @@ public abstract class Client { } /** + * A version of {@link #submit(Bytecode)} which provides the ability to set per-request options. + * + * @param bytecode request in the form of gremlin {@link Bytecode} + * @param options for the request + * + * @see #submitAsync(Bytecode) + */ +public CompletableFuture submitAsync(final Bytecode bytecode, final RequestOptions options) { +throw new UnsupportedOperationException("This implementation does not support Traversal submission - use a sessionless Client created with from the alias() method"); +} + +/** * Initializes the client which typically means that a connection is established to the server. Depending on the * implementation and configuration this blocking call may take some time. This method will be called * automatically if it is not called directly and multiple calls will not have effect. @@ -518,9 +548,23 @@ public abstract class Client { @Override public CompletableFuture submitAsync(final Bytecode bytecode) { +return submitAsync(bytecode, RequestOptions.EMPTY); +} + +@Override +public CompletableFuture submitAsync(final Bytecode bytecode, final RequestOptions options) { try { -return submitAsync(buildMessage(RequestMessage.build(Tokens.OPS_BYTECODE) -.processor("traversal").addArg(Tokens.ARGS_GREMLIN, bytecode)).create()); +// need to call buildMessage() right away to get client specific configurations, that way request specific +// ones can override as needed +final RequestMessage.Builder request = buildMessage(RequestMessage.build(Tokens.OPS_BYTECODE) + .processor("traversal") + .addArg(Tokens.ARGS_GREMLIN, bytecode)); + +// apply settings if they were made available +options.getBatchSize().ifPresent(batchSize -> request.add(Tokens.ARGS_BATCH_SIZE, batchSize)); +options.getTimeout().ifPresent(timeout -> request.add(Tokens.ARGS_SCRIPT_EVAL_TIMEOUT, timeout)); + +return submitAsync(request.create()); } catch (Exception ex) { throw new RuntimeException(ex); }
[tinkerpop] 02/02: TINKERPOP-2211 Added method to set RequestOptions using with()
This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch TINKERPOP-2211 in repository https://gitbox.apache.org/repos/asf/tinkerpop.git commit bebd9e72c6a32736d890c0029d6581143ee5e139 Author: Stephen Mallette AuthorDate: Wed May 8 14:53:39 2019 -0400 TINKERPOP-2211 Added method to set RequestOptions using with() For bytecode based traversals --- CHANGELOG.asciidoc | 2 + docs/src/upgrade/release-3.4.x.asciidoc| 49 ++ .../gremlin/process/remote/RemoteConnection.java | 10 + .../gremlin/structure/io/gryo/GryoVersion.java | 4 +- .../driver/remote/DriverRemoteConnection.java | 19 - .../gremlin/server/GremlinServerIntegrateTest.java | 29 + 6 files changed, 101 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index 05f17a9..fa485a1 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -29,6 +29,8 @@ This release also includes changes from <>. * Changed definition of generic in signature of `from(Traversal)` and `to(Traversal)` steps to use a wildcard rather than `Vertex`. * Fixed problem with connection pool sizing and retry. * Changed `:>` in Gremlin Console to submit the client-side timeout on each request. +* Added option to set per-request settings on a `Traversal` submitted via `Bytecode`. +* Fixed the Gryo registration for `OptionsStrategy` as it was not serializing state properly. [[release-3-4-1]] === TinkerPop 3.4.1 (Release Date: March 18, 2019) diff --git a/docs/src/upgrade/release-3.4.x.asciidoc b/docs/src/upgrade/release-3.4.x.asciidoc index 7f598ea..8afcb8f 100644 --- a/docs/src/upgrade/release-3.4.x.asciidoc +++ b/docs/src/upgrade/release-3.4.x.asciidoc @@ -27,13 +27,22 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima Please see the link:https://github.com/apache/tinkerpop/blob/3.4.2/CHANGELOG.asciidoc#release-3-4-2[changelog] for a complete list of all the modifications that are part of this release. -== TinkerPop 3.4.1 +=== Upgrading for Users -*Release Date: March 18, 2019* + Per Request Options -Please see the link:https://github.com/apache/tinkerpop/blob/3.4.1/CHANGELOG.asciidoc#release-3-4-1[changelog] for a complete list of all the modifications that are part of this release. +In 3.4.0, the notion of `RequestOptions` were added so that users could have an easier way to configure settings on +individual requests made through the Java driver. While that change provided a way to set those configurations for +script based requests, it didn't include options to make those settings in a `Traversal` submitted via `Bytecode`. In +this release those settings become available via `with()` step on the `TraversalSource` as follows: -=== Upgrading for Users +[source,java] + +GraphTraversalSource g = traversal().withRemote(conf); +List vertices = g.with(RemoteConnection.PER_REQUEST_TIMEOUT, 500).V().out("knows").toList() + + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-2211[TINKERPOP-2211] Gremlin Console Timeout @@ -46,14 +55,35 @@ As of 3.4.0, the Java Driver API allowed for timeout settings to be more easily was modified for this current version to pass the console timeout for each remote submission thus yielding more consistent and intuitive behavior. -link:https://issues.apache.org/jira/browse/TINKERPOP-2203[TINKERPOP-2203] +See: link:https://issues.apache.org/jira/browse/TINKERPOP-2203[TINKERPOP-2203] + +=== Upgrading for Providers + + Graph Driver Providers + += Per Request Options + +In GraphBinary serialization, Java `write()` and `writeValue()` from `TypeSerializer` interface now take a Netty's +`ByteBuf` instance instead of an `ByteBufAllocator`, that way the same buffer instance gets reused during the write +of a message. Additionally, we took the opportunity to remove the unused parameter from `ResponseMessageSerializer`. + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-2161[TINKERPOP-2161] + +== TinkerPop 3.4.1 + +*Release Date: March 18, 2019* + +Please see the link:https://github.com/apache/tinkerpop/blob/3.4.1/CHANGELOG.asciidoc#release-3-4-1[changelog] for a complete list of all the modifications that are part of this release. + +=== Upgrading for Users Mix SPARQL and Gremlin In the initial release of `sparql-gremlin` it was only possible to execute a SPARQL query and have it translate to Gremlin. Therefore, it was only possible to write a query like this: -```text +[source,text] + gremlin> g.sparql("SELECT ?name ?age WHERE { ?person v:name ?name . ?person v:age ?age }") ==>[name:marko,age:29] ==>[name:vadas,age:27] @@ -66,11 +96,12 @@ gremlin> g.sparql("SELECT * WHERE { }") ==>v[4] ==>v[5] ==>v[6] -``` + In this release, however, it is now possible to further process that result with Gremlin steps: -```text
[GitHub] [tinkerpop] spmallette commented on issue #1105: TINKERPOP-2205 Change connection management to single request per channel
spmallette commented on issue #1105: TINKERPOP-2205 Change connection management to single request per channel URL: https://github.com/apache/tinkerpop/pull/1105#issuecomment-490462460 > I would be happy to jump on a call/chat to help you understand the architecture of the changes better. Let me know if that is required. thanks, but i think i follow what's been done. > Do we have a tentative release timeline for 3.5.0 yet? No, but we're just starting so I imagine it will take at least through summer to get enough "new" stuff in place to release. > I will write another create slate version for 3.5 later. Couple of additional things I want to fix as part of the clean slate version is to unify the client API, better DNS resolution for potential hosts in the cluster, additional load balancing strategies, ability for providers to plug in information in the request etc. wow - sounds good > Adding additional integration/stress/smoke tests. Unless you have some gaps somewhere that you are aware of, I don't think you need to add anything extra just for the sake of "more tests". You didn't remove any of the old tests (except for one and you had reason for doing so) and they still all work so that inspires confidence. > Adding a config parameter to fallback to old code. More on this below toward the end > Provide a document on working of the new code prior to merge which can be reviewed by the community for potential bugs/design deficiency. From a documentation perspective, I think that this PR should include: 1. Fixes to the current reference documentation to: a. remove references to deprecated configuration options that are now "do nothing" b. include details on best practices for configuring the driver given your new changes 2. Write upgrade documentation to help promote the change and why it was necessary, pointing out what will stop working if you upgrade I think that leads me to my problem with merging this to 3.4.x - If someone upgrades from 3.4.1 to 3.4.2 with this change, their configuration options are no longer relevant. They will just be ignored so if the user managed to get their configuration "perfect" under the old model, they now have to change that given this upgrade. Perhaps that's a simple change (maybe??), but it's a change nonetheless. In TinkerPop's rendition of semantic versioning, `z` upgrades in `x.y.z` should, ideally, have limited impact to users. We occasionally allow breaks in behavior (rarely, if ever, in compilation) in these release versions, but typically those breaks in behavior are the result of a bug fix that can't be resolved any other way. So that said, in a perfect world, your change destined fro 3.4.2 could be staged as a new feature that is parallel to what we already had and the "switch" you suggested earlier could do that. Preferably, we would default to the old functionality with an active switch users would select to utilize the new functionality. Perhaps the "switch" would just be a new `Channelizer` implementation? We could mark the current one as deprecated and then remove it completely in 3.5.0? I guess the changes run deeper than just the `Channelizer` so that may be too simple a solutionwhat were you thoughts on what a "switch" would look like? This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
[tinkerpop] branch master updated: Correct sample custom serializer for GraphBinary CTR
This is an automated email from the ASF dual-hosted git repository. jorgebg pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git The following commit(s) were added to refs/heads/master by this push: new 25e185f Correct sample custom serializer for GraphBinary CTR 25e185f is described below commit 25e185f95426bd812b727b57620eb894a7eee1ef Author: Jorge Bay Gondra AuthorDate: Wed May 8 13:35:39 2019 +0200 Correct sample custom serializer for GraphBinary CTR --- .../types/sample/SamplePersonSerializer.java | 64 ++ .../types/sample/SamplePersonSerializerTest.java | 22 2 files changed, 62 insertions(+), 24 deletions(-) diff --git a/gremlin-driver/src/test/java/org/apache/tinkerpop/gremlin/driver/ser/binary/types/sample/SamplePersonSerializer.java b/gremlin-driver/src/test/java/org/apache/tinkerpop/gremlin/driver/ser/binary/types/sample/SamplePersonSerializer.java index 7efe0ea..03b54c3 100644 --- a/gremlin-driver/src/test/java/org/apache/tinkerpop/gremlin/driver/ser/binary/types/sample/SamplePersonSerializer.java +++ b/gremlin-driver/src/test/java/org/apache/tinkerpop/gremlin/driver/ser/binary/types/sample/SamplePersonSerializer.java @@ -25,6 +25,7 @@ import org.apache.tinkerpop.gremlin.driver.ser.binary.GraphBinaryReader; import org.apache.tinkerpop.gremlin.driver.ser.binary.GraphBinaryWriter; import org.apache.tinkerpop.gremlin.driver.ser.binary.types.CustomTypeSerializer; +import java.nio.charset.StandardCharsets; import java.util.Date; /** @@ -51,13 +52,29 @@ public final class SamplePersonSerializer implements CustomTypeSerializer buffer.readableBytes()) { +throw new SerializationException( +String.format("Not enough readable bytes: %d (expected %d)", valueLength, buffer.readableBytes())); +} final String name = context.readValue(buffer, String.class, false); final Date birthDate = context.readValue(buffer, Date.class, false); @@ -66,35 +83,34 @@ public final class SamplePersonSerializer implements CustomTypeSerializer
[tinkerpop] branch master updated: Include javadoc for GraphBinaryReader and GraphBinaryWriter CTR
This is an automated email from the ASF dual-hosted git repository. jorgebg pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git The following commit(s) were added to refs/heads/master by this push: new 6538c9e Include javadoc for GraphBinaryReader and GraphBinaryWriter CTR 6538c9e is described below commit 6538c9e15e183decf55e30b73cfff13ded0d2dfc Author: Jorge Bay Gondra AuthorDate: Wed May 8 11:45:41 2019 +0200 Include javadoc for GraphBinaryReader and GraphBinaryWriter CTR --- .../driver/ser/binary/GraphBinaryReader.java | 30 ++ .../driver/ser/binary/GraphBinaryWriter.java | 17 2 files changed, 47 insertions(+) diff --git a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryReader.java b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryReader.java index ee012fe..e88c752 100644 --- a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryReader.java +++ b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryReader.java @@ -21,6 +21,30 @@ package org.apache.tinkerpop.gremlin.driver.ser.binary; import io.netty.buffer.ByteBuf; import org.apache.tinkerpop.gremlin.driver.ser.SerializationException; +/** + * Reads a value from a buffer using the {@link TypeSerializer} instances configured in the + * {@link TypeSerializerRegistry}. + * + * + * This class exposes two different methods to read a value from a buffer: {@link GraphBinaryReader#read(ByteBuf)} + * and {@link GraphBinaryReader#readValue(ByteBuf, Class, boolean)}: + * + * {@code read()} method expects a value in fully-qualified format, composed of + * {type_code}{type_info}{value_flag}{value}. + * {@code readValue()} method expects a {value_flag}{value} when a value is nullable and + * only {value} when a value is not nullable. + * + * + * + * + * + * The {@link GraphBinaryReader} should be used to read a nested known type from a {@link TypeSerializer}. + * For example, if a POINT type is composed by two doubles representing the position in the x and y axes, a + * {@link TypeSerializer} for POINT type should use the provided {@link GraphBinaryReader} instance to read those + * two double values. As x and y values are expected to be provided as non-nullable doubles, the method + * {@code readValue()} should be used: {@code readValue(buffer, Double.class, false)} + * + */ public class GraphBinaryReader { private final TypeSerializerRegistry registry; @@ -34,6 +58,12 @@ public class GraphBinaryReader { /** * Reads a value for an specific type. + * + * When the value is nullable, the reader expects the {value_flag}{value} to be contained in the + * buffer. + * + * When the value is not nullable, the reader expects only the {value} to be contained in the + * buffer. */ public T readValue(final ByteBuf buffer, final Class type, final boolean nullable) throws SerializationException { if (buffer == null) { diff --git a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryWriter.java b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryWriter.java index 68ccc7a..ac22e05 100644 --- a/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryWriter.java +++ b/gremlin-driver/src/main/java/org/apache/tinkerpop/gremlin/driver/ser/binary/GraphBinaryWriter.java @@ -24,6 +24,23 @@ import org.apache.tinkerpop.gremlin.driver.ser.SerializationException; import org.apache.tinkerpop.gremlin.driver.ser.binary.types.CustomTypeSerializer; import org.apache.tinkerpop.gremlin.driver.ser.binary.types.TransformSerializer; +/** + * Writes a value to a buffer using the {@link TypeSerializer} instances configured in the + * {@link TypeSerializerRegistry}. + * + * + * This class exposes two different methods to write a value to a buffer: + * {@link GraphBinaryWriter#write(Object, ByteBuf)} and + * {@link GraphBinaryWriter#writeValue(Object, ByteBuf, boolean)}: + * + * {@code write()} method writes the binary representation of the + * {type_code}{type_info}{value_flag}{value} components. + * {@code writeValue()} method writes the {value_flag}{value} when a value is nullable and + * only {value} when a value is not nullable. + * + * + * + */ public class GraphBinaryWriter { private final TypeSerializerRegistry registry; private final static byte VALUE_FLAG_NULL = 1;