Changes (1)

Official information may be found at the [Java Client Library|http://www.couchbase.com/develop/java/current] page.

h2. Other Languages on the JVM

Michael Nitschinger has written a blog on [Accessing Couchbase from Scala|http://nitschinger.at/Accessing-Couchbase-from-Scala]

h2. Handling Timeouts

The Java client library has a set of synchronous and asynchronous methods. While it doesn't happen in most situations, occasionally network IO can become congested, nodes can fail, or memory pressure can lead to situations where an operation can timeout.

When this timeout occurs, most of the synchronous methods on the client will return a RuntimeException showing a timeout as the root cause. Since the asynchronous operations give finer grained control over how long is given for an operation to be successful or unsuccessful, this path throws a checked TimeoutException.

As an application developer, it's best to think about what you would do after this timeout. This may be something like showing the end user a message, it may be nothing, or it may be going to some other system for additional data.

In some cases, it may make sense to retry the operation, but this should be thought about carefully, as the cause of the timeout may be exacerbated. In the case of deciding to retry, doing this with a backoff or exponential backoff (see bulk loading below for an example) is advisable. This can be conceptually thought of as a pressure relief valve for intermittent resource contention.

h3. Timeout Instead of Blocking

In the case that the application code calling the client is very quickly creating a large number of asynch operations, one may also see timeouts immediately upon requesting operations. Creating of an asynch operation is really a matter of creating the object and putting it on a request queue. These are all local-to-the-system memory operations that require some amount of IO to be serviced.

Rather than allow the application to issue so many asynch operations that the JVM becomes overwhelmed and runs into an OOM condition, the default behavior of the client library is to start to immediately timeout asynch operations if the queue of operations to be sent to the server is overwhelmed.

If, for your application purposes, it'd be better to have some blocking when requesting these asynch operations because your application is issuing them at an extreme rate (example, bulk loading), that behavior can be configured like so:

When doing bulk loading of Couchbase Server, one can frequently overwhelm available memory in the Couchbase cluster before it can store data on disk. When this happens, Couchbase Server will immediately send a response back indicating the operation cannot be handled at the moment, but likely can be handled later. This is sometimes referred to as "handling Temp OOM" (where OOM means out of memory), though the actual temporary failure could be sent back for reasons other than OOM. Temporary OOM is the most common, however.

There are plans for future client support to handle this automatically, but handling it in your application is really a matter of a simple do-while.

// note that other failure cases fall through. status.isSuccess() can be // checked for success or failure or the message can be retrieved. return result; } } {code}

Make sure you use this along with some tuning to be sure operations aren't immediately timed out if there are too many outstanding asynch operations. {code} List<URI> baselist = new ArrayList<URI>(); baselist.add(new URI("http://localhost:8091/pools"));

CouchbaseConnectionFactoryBuilder cfb = new CouchbaseConnectionFactoryBuilder(); cfb.setOpTimeout(10000); // wait up to 10 seconds for an operation to succeed cfb.setOpQueueMaxBlockTime(5000); // wait up to 5 seconds when trying to enqueue an operation

This code sample originally appeared in [this gist|https://gist.github.com/2232909] by&nbsp;[Matt Ingenthron|~ingenthr].

h2. Configuring Logging

Occasionally when troubleshooting an issue with a clustered deployment, it may be required to gather additional information from the Couchbase Java Client's logging. It uses JDK logging and this can be configured by configuring a runtime define and adding some additional logging properties.

Other methods of enabling the additional logging may be appropriate depending on the deployment.

Since the Couchbase Java Client uses spymemcached and is compatible with spymemcached (we wrote it too, we like it\!), if you want to set its built in logging to either JDK standard logging or log4j, simply use {code}-Dnet.spy.log.LoggerImpl=net.spy.memcached.compat.log.SunLogger{code} or {code}-Dnet.spy.log.LoggerImpl=net.spy.memcached.compat.log.Log4JLogger{code}

h3. Configuring Logging Programmatically

Sometimes, if you're writing in an IDE which is handling all the command line stuff for you, you just want to express your logging in code. That's possible too. Just add a section like this to your code:

Currently, with Couchbase Server 2.0 loading views is done through the web console, which gives the developer a good way to iterate quickly with view development.

However, once the view is developed, it's convenient to load any views programmatically and store them in a source control repository alongside other application source code. Since loading views is simply a matter of an HTTP request, they can be loaded with the command line using curl or even a simple Java program.

With Couchbase Server, if you overwhelm the amount of memory from workload, rather than become slower, Couchbase will send back temporary failures indicating you can retry the operation. &nbsp;This gives the software a bit more control than with other database systems, where they become slower for all operations under load. &nbsp;It is a "relief valve" of sorts, and gives you as an app developer the opportunity to backoff and retry operations if appropriate in your application logic. {code:title=Couchbase Exponential Backoff} package com.couchbase.sample.dataloader;