To follow the tradition of programming tutorials, we'll start with "Hello Couchbase". In the first example, we'll connect to the Cluster, set a simple document, retrieve it and print it out. This first example contains the full sourcecode, but in later example we'll omit the imports and assume we're already connected to the cluster.
Listing 1: Hello Couchbase!
package com.couchbase.examples; import com.couchbase.client.CouchbaseClient; import java.net.URI; import java.util.ArrayList; public class App { public static void main(String[] args) { ArrayList<URI> nodes = new ArrayList<URI>(); // Add one or more nodes of your cluster (exchange the IP with yours) nodes.add(URI.create("http://127.0.0.1:8091/pools")); // Try to connect to the client CouchbaseClient client = null; try { client = new CouchbaseClient(nodes, "default", ""); } catch (Exception e) { System.err.println("Error connecting to Couchbase: " + e.getMessage()); System.exit(1); } // Set your first document with a key of "hello" and a value of "couchbase!" int timeout = 0; // 0 means store forever client.set("hello", timeout, "couchbase!"); // Return the result and cast it to string String result = (String)client.get("hello"); System.out.println(result); // Shutdown the client client.shutdown(); } }
While this code should be very easy to grasp, there is a lot going on worth a little more discussion:
Connecting: the CouchbaseClient accepts a List of
URIs that point to nodes in the Cluster.
While passing in only one URI is fine, it
is strongly recommended to add two or three (of course if your
cluster has more than one node). It is important to understand
that this list does not have to contain all nodes in the
cluster - you just need to provide a few so that during the
initial bootstrap phase the Client is able to connect to the
server. After this has happened, the Client automatically
fetches the cluster configuration and keeps it up to date,
even when the cluster topology changes. This means that you
don't need to change your application config at all when you
need to resize your cluster. Also keep in mind to use a URI
exactly like http://[YOUR-NODE]:8091/pools
(and not just the IP-Address for example) - this is sometimes
called the bootstrap URI.
The next two arguments are for the bucket
and the password. The bucket is the
container for all your documents. Inside a bucket, a key - the
identifier for a document - must be unique. In production
environments, it is recommended to use a password on a bucket
(this can be configured during bucket creation), but when you
are just starting out using the default
bucket without a password is fine. Note that the
beer-sample bucket also doesn't have a
password, so just change the bucket name and you're set.
Set and get: these two
operations are one of the most fundamental ones. You can use
set to create or override a document inside
your bucket and get to read it back
afterwards. There are lots of arguments and variations, but if
you just use them as shown in the previous example will get
you pretty far. Note that the get operation
doesn't care what you read out of the bucket, so you need to
cast it into the format you want (in our case we did store a
string, so it makes sense to convert it back later).
Disconnecting: at the end of the program (or when you shutdown
your server instance), you should use the
shutdown method to prevent the loss of
data. If used without arguments, it will wait until all
outstanding operations have been finished (but no new ones
will be accepted). You can also call it with a maximum waiting
time which makes sense if you (potentially) don't want to wait
forever.
By default, the logger is configured to log from
INFO upwards. This means that by default, a
decent amount of helpful information is logged automatically. In
our example above, the logs look like this:
2012-12-03 18:57:45.777 INFO com.couchbase.client.CouchbaseConnection: Added {QA sa=/127.0.0.1:11210, #Rops=0, #Wops=0, #iq=0, topRop=null, topWop=null, toWrite=0, interested=0} to connect queue 2012-12-03 18:57:45.788 INFO com.couchbase.client.CouchbaseConnection: Connection state changed for sun.nio.ch.SelectionKeyImpl@76f8968f 2012-12-03 18:57:45.807 INFO com.couchbase.client.ViewConnection: Added localhost to connect queue 2012-12-03 18:57:45.808 INFO com.couchbase.client.CouchbaseClient: viewmode property isn't defined. Setting viewmode to production mode couchbase! 2012-12-03 18:57:45.925 INFO com.couchbase.client.CouchbaseConnection: Shut down Couchbase client 2012-12-03 18:57:45.929 INFO com.couchbase.client.ViewConnection: Node localhost has no ops in the queue 2012-12-03 18:57:45.929 INFO com.couchbase.client.ViewNode: I/O reactor terminated for localhost
You can see to which nodes the client connects (hopefully every node in the cluster), which viewmode is used (more on that later) and other helpful output. These logs provide vital information when a issue needs to be debugged (be it through the community forums or through paid Couchbase Support).