DESCRIPTION

JCBC-849: Subdocument client API

Motivation:
-----------
Subdocument API allows to mutate and read specific fragments of JSON
inside an existing document without having to transfer the whole
document over the wire.

Modifications:
--------------
Added the DocumentFragment class, both serving as an input parameter
for mutation and a return parameter. Additionally to what would be
available in a top-level Document, it also bears a path (pointing to a
specific value inside the JSON).

Added Bucket level API for Subdoc:
 - simple operations (getIn, existIn, insertIn, replaceIn, upsertIn,
   removeIn)
 - array operations (extendIn, arrayInsertIn, addUniqueIn)
 - arithmetic operation (counterIn)
 - multiple lookups (lookupIn)
 - multiple mutations (mutateIn)

Multi operations have their own return types.

Added associated exceptions as subclasses of SubDocumentException.
Added a method in JsonTranscoder to transcode any Object to a ByteBuf.

Result:
-------
The subdoc API can be used for efficient modification of JSON documents.
Integration tests validate the behavior of the API on cluster >= 4.5.0.

Change-Id: Ifce305713329f0d63073fab3012129211e4c41f6


COMMENTS

author: Estrella Humphrey
date: 2016-01-14 14:13:36.985000000

Uploaded patch set 11.

-------------------------------------
author: Estrella Humphrey
date: 2016-01-14 14:13:53.041000000

Patch Set 11: Verified+1

-------------------------------------
author: Natasha Sullivan
date: 2016-01-19 08:21:29.977000000

Patch Set 11:

(49 comments)

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/CannotInsertValueException.java -> license

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/ValueTooDeepException.java -> license

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/PathNotFoundException.java -> license

Line:15, src/main/java/com/couchbase/client/java/error/subdoc/PathNotFoundException.java -> maybe name it PathDoesNotExistException to align it with the Path(Already)ExistsException and DocumentDoesNotExistException?

Line:1, src/main/java/com/couchbase/client/java/document/subdoc/MultiLookupResult.java -> license

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/PathMismatchException.java -> license

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/MultiMutationException.java -> license

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/DocumentNotJsonException.java -> license

Line:1368, src/main/java/com/couchbase/client/java/CouchbaseAsyncBucket.java -> is invalid only bound to arrays?

Line:1509, src/main/java/com/couchbase/client/java/CouchbaseAsyncBucket.java -> looks like indentation is off here

Line:1643, src/main/java/com/couchbase/client/java/CouchbaseAsyncBucket.java -> does still need to be addressed?

Line:951, src/main/java/com/couchbase/client/java/CouchbaseBucket.java -> what about createParents = true overloads?

Line:963, src/main/java/com/couchbase/client/java/CouchbaseBucket.java -> what about createParents = true overloads?

Line:987, src/main/java/com/couchbase/client/java/CouchbaseBucket.java -> what about createParents = true overloads?

Line:1, src/main/java/com/couchbase/client/java/document/subdoc/ExtendDirection.java -> license

Line:8, src/main/java/com/couchbase/client/java/document/subdoc/ExtendDirection.java -> can you add docs to both directions to indicate what they mean?

Line:16, src/main/java/com/couchbase/client/java/error/subdoc/SubDocumentException.java -> okay so here is an idea: maybe we should rename this to something like DocumentFragmentException? Since the name "subdoc" is something we use, but don't really expose - right?

if you get a document fragment exception you can spot that its related to document fragments.. or is there a reason that this is a really bad idea?

Or we can think about renaming the DocumentFragment to SubDocument? but this would not align with the spec :/

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/PathExistsException.java -> license

Line:19, src/main/java/com/couchbase/client/java/error/subdoc/PathExistsException.java -> what about PathAlreadyExistsException? So it's in line with "DocumentAlreadyExistsException"

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/DeltaTooBigException.java -> license

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/DocumentTooDeepException.java -> license

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/ZeroDeltaException.java -> license header missing

Line:7, src/main/java/com/couchbase/client/java/error/subdoc/ZeroDeltaException.java -> is this something defined in the protocol as mandatory? Since on the counter op in general KV we don't have such a thing happen - in fact, there I think it just returns the same value?

Line:1, src/main/java/com/couchbase/client/java/document/subdoc/LookupResult.java -> license

Line:16, src/main/java/com/couchbase/client/java/document/subdoc/LookupResult.java -> any reason values and constructor are protected and not private?

Line:1, src/main/java/com/couchbase/client/java/document/subdoc/LookupSpec.java -> license

Line:20, src/main/java/com/couchbase/client/java/document/subdoc/LookupSpec.java -> can this be made private instead of package private?

Line:37, src/main/java/com/couchbase/client/java/util/features/CouchbaseFeature.java -> unrelated, but can you file another changeset and bump n1ql and spatial to 4.0? since we technically never had a 3.5 :D

Line:1, src/main/java/com/couchbase/client/java/document/subdoc/MultiMutationResult.java -> license

Line:8, src/main/java/com/couchbase/client/java/document/subdoc/MultiMutationResult.java -> representS

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/NumberTooBigException.java -> license

Line:9, src/main/java/com/couchbase/client/java/error/subdoc/NumberTooBigException.java -> I think this will leave java users confused. It would be good to look up the ranges and see how they compare to java number ranges

Line:1, src/main/java/com/couchbase/client/java/document/subdoc/DocumentFragment.java -> license

Line:20, src/main/java/com/couchbase/client/java/document/subdoc/DocumentFragment.java -> What do you think about adding a DocumentFragment<T> interface and implementing it as Json or DefaultDocumentFragment? 

I know right now there are no other impls, but who knows.. a little like we do with Bucket and Cluster :)

Line:21, src/main/java/com/couchbase/client/java/document/subdoc/DocumentFragment.java -> Can you add the .create() factory methods so the fragment works very much like a Document? (like JsonDocument.create())

Line:31, src/main/java/com/couchbase/client/java/document/subdoc/DocumentFragment.java -> I think the ID is mandatory, right? If so we can add the same checks as in the AbstractDocument instance (not null, length, and expiry)

Line:40, src/main/java/com/couchbase/client/java/document/subdoc/DocumentFragment.java -> reuse constructors?

Line:53, src/main/java/com/couchbase/client/java/document/subdoc/DocumentFragment.java -> docblocks on the getters here pay off I think since its one of the primary new objects to work with.

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/PathInvalidException.java -> license

Line:15, src/main/java/com/couchbase/client/java/error/subdoc/PathInvalidException.java -> the naming is a little odd - maybe turn it around? "InvalidPathException"

Line:1, src/main/java/com/couchbase/client/java/error/subdoc/PathTooDeepException.java -> license

Line:1, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> license

Line:26, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> can this be made private?

Line:57, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> formatting

Line:75, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> should we add an overload where createParents = true?

Line:86, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> should we add an overload where createParents = true?

Line:99, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> should we add an overload where createParents = true?

Line:122, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> on the single mutation API createParents is exposed, is this not supported on multi op?

Line:132, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> on the single mutation API createParents is exposed, is this not supported on multi op?

-------------------------------------
author: Estrella Humphrey
date: 2016-01-19 12:06:10.516000000

Patch Set 11:

(13 comments)

on adding overloads for createParents = true:

that would add even more to the API surface (10 new methods in Bucket, 5 in AsyncBucket, 5 in MutationSpec) but I can add that if you think it's necessary.

should the default be true though? this hasn't been discussed in the RFC.

Line:15, src/main/java/com/couchbase/client/java/error/subdoc/PathNotFoundException.java -> followed the RFC

Line:1368, src/main/java/com/couchbase/client/java/CouchbaseAsyncBucket.java -> these status code have a special meaning in this operation that is defined in the spec, however it could be that the error is actually one of the more generic cases? (no way to determine this)

Line:951, src/main/java/com/couchbase/client/java/CouchbaseBucket.java -> see toplevel comment

Line:963, src/main/java/com/couchbase/client/java/CouchbaseBucket.java -> see toplevel comment

Line:987, src/main/java/com/couchbase/client/java/CouchbaseBucket.java -> see toplevel comment

Line:16, src/main/java/com/couchbase/client/java/error/subdoc/SubDocumentException.java -> I don't think we should rename the DocumentFragment.
However a few exceptions are not related to the fragment itself, or less clearly related: DocumentNotJsonException, or any exception occurring on a getIn/existIn (since those didn't take a DocumentFragment as input).
Also we mention the sub-document feature in the javadocs...
I do not have a strong opinion on what to do there.

Line:19, src/main/java/com/couchbase/client/java/error/subdoc/PathExistsException.java -> followed the RFC which was less verbose (and follows the logic of all path-related exceptions starting with Path)

Line:7, src/main/java/com/couchbase/client/java/error/subdoc/ZeroDeltaException.java -> yes, this is defined in the protocol

Line:20, src/main/java/com/couchbase/client/java/document/subdoc/DocumentFragment.java -> Subdoc is JSON only, but I can add an interface (I propose IDocumentFragment, so that users looking at the RFC/other implems find DocumentFragment by default).

This could maybe make sense for the equivalent to RawJsonDocument? But then we have to implement transcoders or at least encoding/decoding logic in all operations...

Line:15, src/main/java/com/couchbase/client/java/error/subdoc/PathInvalidException.java -> followed the RFC with logic that all path-related exceptions start with Path

Line:75, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> see toplevel comment

Line:86, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> see toplevel comment

Line:99, src/main/java/com/couchbase/client/java/document/subdoc/MutationSpec.java -> see toplevel comment

-------------------------------------
author: Tate Garrett
date: 2016-01-19 18:11:19.321000000

Change has been successfully cherry-picked as 3fc6a62fd89c15dcc9f392593cf56020fb1ddc3a

-------------------------------------
