com.couchbase.client.java.subdoc

Class AsyncLookupInBuilder

java.lang.Object

com.couchbase.client.java.subdoc.AsyncLookupInBuilder

@InterfaceStability.Committed
 @InterfaceAudience.Public
public class AsyncLookupInBuilder
extends Object

A builder for subdocument lookups. In order to perform the final set of operations, use the execute() method. Operations are performed asynchronously (see LookupInBuilder for a synchronous version).

Instances of this builder should be obtained through AsyncBucket.lookupIn(String) rather than directly constructed.

Since:

2.2

Author:

Simon Baslé

Constructor Summary

Constructors

Constructor and Description
AsyncLookupInBuilder(ClusterFacade core, String bucketName, CouchbaseEnvironment environment, FragmentTranscoder transcoder, String docId) Instances of this builder should be obtained through AsyncBucket.lookupIn(String) rather than directly constructed.

Method Summary

Modifier and Type	Method and Description
protected Observable<DocumentFragment<Lookup>>	doMultiLookup()
protected Observable<DocumentFragment<Lookup>>	doSingleLookup(LookupSpec spec)
Observable<DocumentFragment<Lookup>>	execute() Perform several lookup operations inside a single existing JSON document.
AsyncLookupInBuilder	exists(String... paths) Check if a value exists inside the document (if it does not, attempting to get the DocumentFragment.content(int) will raise an error).
AsyncLookupInBuilder	get(String... paths) Get a value inside the JSON document.
AsyncLookupInBuilder	includeRaw(boolean includeRaw) Set to true, includes the raw byte value for each GET in the results, in addition to the deserialized content.
boolean	isIncludeRaw()
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AsyncLookupInBuilder

@InterfaceAudience.Private
public AsyncLookupInBuilder(ClusterFacade core,
                                                       String bucketName,
                                                       CouchbaseEnvironment environment,
                                                       FragmentTranscoder transcoder,
                                                       String docId)

Instances of this builder should be obtained through AsyncBucket.lookupIn(String) rather than directly constructed.

Method Detail

execute

public Observable<DocumentFragment<Lookup>> execute()

Perform several lookup operations inside a single existing JSON document. The list of path to look for inside the JSON is constructed through builder methods get(String...) and exists(String...).

The subdocument API has the benefit of only transmitting the fragment of the document you work with on the wire, instead of the whole document.

If multiple operations are specified, each spec will receive an answer, overall contained in a DocumentFragment, meaning that if sub-document level error conditions happen (like the path is malformed or doesn’t exist), the whole operation still succeeds.

If a single operation is specified, then any error other that a path not found will cause the Observable to fail with the corresponding SubDocumentException. Otherwise a DocumentFragment is returned.

Calling DocumentFragment.content(String) or one of its variants on a failed spec/path will throw the corresponding SubDocumentException. For successful gets, it will return the value (or null in the case of a path not found, and only in this case). For exists, it will return true (or false for a path not found).

To check for any error without throwing an exception, use DocumentFragment.status(String) (or its index-based variant).

To check that a given path (or index) is valid for calling content() on it without raising an Exception, use DocumentFragment.exists(String).

One special fatal error can also happen, when the value couldn’t be decoded from JSON. In that case, the ResponseStatus for the path is ResponseStatus.FAILURE and the content(path) will throw a TranscodingException.

This Observable most notable error conditions are:

• The enclosing document does not exist: DocumentDoesNotExistException
• The enclosing document is not JSON: DocumentNotJsonException
• No lookup was defined through the builder API: IllegalArgumentException

Other document-level error conditions are similar to those encountered during a document-level AsyncBucket.get(String).

Returns:

an Observable of a single DocumentFragment representing the whole list of results (1 for each spec), unless a document-level error happened (in which case an exception is propagated).

includeRaw

public AsyncLookupInBuilder includeRaw(boolean includeRaw)

Set to true, includes the raw byte value for each GET in the results, in addition to the deserialized content.

isIncludeRaw

public boolean isIncludeRaw()

Returns:

true if this builder is configured to include raw byte values for each GET result.

get

public AsyncLookupInBuilder get(String... paths)

Get a value inside the JSON document.

Parameters:

paths - the path inside the document where to get the value from.

Returns:

this builder for chaining.

exists

public AsyncLookupInBuilder exists(String... paths)

Check if a value exists inside the document (if it does not, attempting to get the DocumentFragment.content(int) will raise an error). This doesn’t transmit the value on the wire if it exists, saving the corresponding byte overhead.

Parameters:

paths - the path inside the document to check for existence.

Returns:

this builder for chaining.

doSingleLookup

protected Observable<DocumentFragment<Lookup>> doSingleLookup(LookupSpec spec)

doMultiLookup

protected Observable<DocumentFragment<Lookup>> doMultiLookup()

toString

public String toString()

Overrides:

toString in class Object