Details
-
Task
-
Resolution: Fixed
-
Major
-
2.1.4
-
Security Level: Public
Description
Currently the description for upsert in the javadoc is as follows (line 1384 at https://github.com/couchbase/couchbase-java-client/blob/master/src/main/java/com/couchbase/client/java/Bucket.java):
<D extends Document<?>> D upsert(D document);
|
|
/**
|
* Insert or replace a {@link Document} with a custom timeout.
|
This is somewhat misleading as it suggests that upsert will insert a document (as per the built-in `insert` method, which is correct) or it will replace the document based on document existence. While technically the document is replaced within Couchbase, the replacement method is not the same as that of the built in `replace` function, which uses a CAS-value.
This could cause some confusion as users of the SDK may believe that the behaviour for `upsert` will be the same as that of `insert` or `replace` based on whether or not the document already exists.
We should be careful about the terminology we use in order to prevent this type of confusion and the JavaDoc for this method should be updated to reflect that.
Perhaps the use of the word 'overwrite' instead of 'replace' would be more appropriate in this context?
Attachments
For Gerrit Dashboard: JCBC-844 | ||||||
---|---|---|---|---|---|---|
# | Subject | Branch | Project | Status | CR | V |
56630,2 | JCBC-844: Clarify javadocs of upsert. | master | couchbase-java-client | Status: MERGED | +2 | +1 |