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

Need clear info and examples on proper error handling

    Details

      Description

      It's very difficult for people to understand the error handling behavior of the client library, and how to properly handle errors. The async methods make it even more difficult. Information is spread across multiple sections, hidden in individual method descriptions, or else not mentioned at all. The docs should provide a clear description of how to use the API correctly, including example code that does correct error handling that can be cut-and-pasted.

      There is a brief mention of error handling here, but it's hidden and very cursory, with no example code:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/create-update-docs.html

      This doc mentions that .get() returns null on failure, but gives no hints on how to determine why, or what the right way to recover is:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/read-docs.html

      This gives a very cursory mention of failure, but no way to get further details:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/delete-docs.html

      No mention of JSON encoding errors or what to expect:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/json-handling-docs.html

      Mentions that OperationFuture may return false even if operation succeeds due to durability requirement failure, but no clear example of how to tell the difference, what status codes to expect in each case, etc.:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/advanced-persistence.html

      Mentions that synchronous call may return an exception, but no info on what the exception would be, or in what circumstances it may return null with no exception:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-summary-synchronous.html

      No mention of .isSuccess() method, or any info on how errors are reported via *Future objects. Also no mention of when the async method may fail immediately vs. when the failure will be reported only after checking .isSuccess() or another method on the future. No mention of what errors are reported as exceptions vs. what errors are reported only via the future object's methods.:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-summary-asynchronous.html

      No mention of when the constructor might fail or what exceptions might be thrown:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-connection.html

      No mention of how to tell if the FALSE result is due to timeout, impossible persistence requirements, or other problem:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-set-observe.html

      Not clear enough that .add(), .set(), .replace() are an async methods, too easy for new user to misunderstand how to use them:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-set-add.html
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-set-set.html
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-update-replace.html

      No mention that .get() may throw an exception, or how errors other than NotFound may be reported:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-get.html

      Yay, here is an example that has a bit of error handling! Unfortunately, it is a "catch(Exception)" (i.e., very generic, and not intended to catch Couchbase-specific errors or timeouts), and no indication of how to handle actual Couchbase errors. Also gives false impression that get() will throw an exception on all failure, when in fact you need to check for failure with .isSuccess() or something.:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-get-async.html

      Also on that page (async get), mentions that a TimeoutException may be thrown. But that won't happen on asyncGet() call, instead it will be when checking .get() on the Future result. I think. It is welcome to list exceptions that can be thrown, but I think this one is incorrect.
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-get-async.html

      .getBulk() and .asyncGetBulk() are complicated enough that they deserve their own example of proper error handling, and what happens when one server node is down and other nodes are up, so partial results are available, etc.:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-bulk.html

      Nice that these pages mention what exceptions can be thrown, so I can infer how to tell a timeout from a not found, etc. But why only here? Shouldn't these exceptions be more generally described elsewhere as applying to all operations (RuntimeException, InterruptedException, OperationTimeoutException)?:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-get-and-lock.html
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-retrieve-unlock.html

      Append and Prepend should normally use 0 for the casunique, and then I would not expect an EXISTS error. The example code is clunky, less efficient (suggests doing a .gets() call just to get the cas id), and likely to fail much more often. The example code does not do proper retry handling on an EXISTS error. It does not show how to distinguish an EXISTS, NOTFOUND, or server down error.:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-update-append.html
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/couchbase-sdk-java-update-prepend.html

      View queries might time out, on all or some servers. Should document how the client should handle errors from view queries. Also, if client requests a view that doesn't exist, how is that handled:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-view.html

      There is no mention of error handling in the "Using the APIs" nor "Java Troubleshooting" sections, either:

      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-started.html
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-troubleshooting.html

      There is a brief mention of RuntimeException being "returned" (should say "thrown") in the section on handling timeouts, but this is too buried and too specific to be of real use. And there is no example code:
      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/api-reference-troubleshooting.html

      Also, the tutorial doesn't do error handling at all, for example:

      http://www.couchbase.com/docs/couchbase-sdk-java-1.1/managing-beers.html

      Look for "client.set" and "client.query" on that page and you'll see it ignores error handling entirely. I think this is a mistake in tutorial code, it should be complete and correct, or at least it should provide a warning saying that there is no error handling, with a link to the docs that describe how to do proper error handling.

        Issue Links

        No reviews matched the request. Check your Options in the drop-down menu of this sections header.

          Activity

            People

            • Assignee:
              daschl Michael Nitschinger
              Reporter:
              TimSmith Tim Smith (Inactive)
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:

                Gerrit Reviews

                There are no open Gerrit changes