Error handling in the Java client library

En mi previous blog article, we looked at the errors thrown by libCouchbase clients such as ruby, python, C and C++. This blog will focus on the Java client library for Couchbase.

In the Java client library, there are exceptions, no errors. Depending on the return type and state of application, different exceptions can be thrown by the java client. Generally, you’ll find those exceptions noted either through the @throws annotations or your IDE will tell you that you need to catch them.

Here are some exceptions that you might encounter when using the Java library:

All asynchronous operations return futures, they do not raise an exception until you block on the result. In addition to trapping the exception, you can also inspect the status of the future and use the getMessage() API to obtain the actual message text.

For synchronous APIs, the client library is implemented as a wrapper around the async methods. Here are the most common exceptions thrown by the syncronous java APIs :

1.     TimeoutException – This means that waiting on the future took longer than expected. For example, this exception is thrown if get() is used with a default timeout value and it expires. It is also thrown if get() with a custom timeout is used and the timeout expires.

2.     CancellationException – This means that the operation was cancelled while “in flight”. For example, a request sent over a network without a reply. This can particularly happen when a node fails. All operations that are currently in flight are cancelled.

3.     InterruptedException– This means that there was a interrupt while blocking on the future.

If you are using views in your application with Java, you might see the following exceptions :

1.    InvalidViewException – This means that an invalid view name or design document was specified. This exception is also thrown if a view is in the development stage and is not deployed to production or the view is in production and the app refers to the development view.

To handle this exception, try using the correct viewname parameter when calling the view and make sure that this view is deployed to production.

If you are using the APIs to verify that your data is persisted by Couchbase, there are a few more exceptions you might want to watch out for:

1.    ObservedException – This means that something general went wrong with API call and more details can be found in the status message.

2.    ObservedTimeoutException – This means that the API call timed out and you must retry.

3.    ObservedModifiedException – This means that the API call failed because the document was modified in the meantime. This indicates a race condition.

Finally, during bootstrapping your application with the Java API you may encounter the following exceptions:

1.    ConfigParsingException – This means that the current configuration cannot be parsed. You must verify the correctness of your config file and try again.

You may also see other network exceptions if the host is not reachable.

Good luck building your applications using the Couchbase Java client. If you have any questions, please do not hesitate to ask us in the forums.