Uploaded image for project: 'Couchbase Java Client'
  1. Couchbase Java Client
  2. JCBC-844

JavaDoc description of `upsert` method is misleading.

    XMLWordPrintable

Details

    • Task
    • Resolution: Fixed
    • Major
    • 2.2.2
    • 2.1.4
    • Documentation
    • 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

        Activity

          People

            daschl Michael Nitschinger
            matt.carabine Matt Carabine (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved:

              Gerrit Reviews

                There are no open Gerrit changes

                PagerDuty