DESCRIPTION

JCBC-921: Implement builder-based API for subdoc

Motivation:
-----------
The common SDK API that was agreed upon for the sub-document feature is
one based on builders. This allows you to fluently describe what lookups
or mutations you want to perform, and the single operation cases can
still be optimized at execution by choosing the right single message to
send to the server.

Modifications:
--------------
Subdoc API at the bucket level is limited to two methods that just take
the key of the document to target: lookupIn and mutateIn. These each
return an adequate builder that can be used to describe either the
lookups or mutations to be performed.

LookupInBuilder uses AsyncLookupInBuilder under the cover, and similarly
MutateInBuilder blocks on AsyncMutateInBuilder. In order to trigger the
operations, one must call doLookup() or doMutate() on the builders.

ExtendDirection has been removed (builder methods are separated for the
two directions).

All results are represented as a DocumentFragment, that allows to get
a result by index or path of the original operation. If a lookup wasn't
successful, calling content() on its path or index will throw the
exception that corresponds to the error.

Most of the subdoc code now is contained in the two async builders and
tests have been updated for the new API.

Result:
-------
Subdocument lookups and mutations can easily be expressed through a
builder-based API.

The API is extensively tested with integration tests.

Change-Id: I0038af9b543464832a15cd204dad20c83ab745eb


COMMENTS

author: Estrella Humphrey
date: 2016-02-19 17:01:27.676000000

Uploaded patch set 6.

-------------------------------------
author: Estrella Humphrey
date: 2016-02-19 17:02:06.033000000

Patch Set 6: Verified+1

-------------------------------------
author: Estrella Humphrey
date: 2016-02-19 17:03:14.634000000

Patch Set 6:

calling in Sergey and Mark for extra review :) Mark maybe at least look at the integration test for an idea of the usage of the API ;)

-------------------------------------
author: Natasha Sullivan
date: 2016-02-19 17:04:27.911000000

Patch Set 6: Code-Review+2

-------------------------------------
author: Wyatt Kramer
date: 2016-02-19 18:29:22.738000000

Patch Set 6:

(2 comments)

Line:180, src/integration/java/com/couchbase/client/java/SubDocumentTest.java -> How does one get the error codes (if any) for other resulrs?

Line:200, src/integration/java/com/couchbase/client/java/SubDocumentTest.java -> From what I understamd, the returned object should contain an .exists() method for this purpose. content() should either return NULL (or even better, raise an exception) if there is no content for this operation (or there was an error)

-------------------------------------
author: Estrella Humphrey
date: 2016-02-19 20:10:22.467000000

Patch Set 6:

(2 comments)

Line:180, src/integration/java/com/couchbase/client/java/SubDocumentTest.java -> for a single mutation, the error will be thrown as an exception. as soon as you chain more than one, a DocumentFragment (or SubdocResults) is instead always returned and you can check the error via content(), status()

Line:200, src/integration/java/com/couchbase/client/java/SubDocumentTest.java -> the exists() method basically returns true if a call to content() with the same path won't throw an exception... I understood that get and exist were supposed to treat PATH_NOT_FOUND as slightly differently? for exist notably, there's no real sense in a method that return either true or an exception.

-------------------------------------
author: Tate Garrett
date: 2016-02-23 18:39:14.344000000

Change has been successfully cherry-picked as 8ccf14088a27669ff29852cf88cd37b2eb471611

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