1ec02294cSMichael Nitschinger# Official Couchbase Java SDK
2f122ff22SMatt Ingenthron
339b41060SMichael NitschingerThis project is the official driver for Couchbase when working with Java (or on the JVM). It provides management, CRUD and query facilities through both asynchronous and synchronous APIs.
4f122ff22SMatt Ingenthron
539b41060SMichael Nitschinger## Features ##
650de8557STugdual Grall
739b41060SMichael Nitschinger* High-Performance Key/Value and Query (N1QL, Views) operations
839b41060SMichael Nitschinger* Cluster-Awareness and automatic rebalance and failover handling
939b41060SMichael Nitschinger* Asynchronous (through [RxJava](https://github.com/ReactiveX/RxJava)) and Synchronous APIs
1039b41060SMichael Nitschinger* Transparent Encryption Support
1139b41060SMichael Nitschinger* Cluster and Bucket level management facilities
1239b41060SMichael Nitschinger* Complete non-blocking stack through [RxJava](https://github.com/ReactiveX/RxJava) and [Netty](http://netty.io)
132117ec8bSMichael Nitschinger
1439b41060SMichael Nitschinger## Getting Help ##
15ff3a0db4SMichael NitschingerThis README, as well as the [reference documentation](https://developer.couchbase.com/documentation/server/5.0/sdk/java/start-using-sdk.html) are the best places to get started and dig deeper into the Couchbase SDK. In addition, you might want to look at our [travel-sample application](https://github.com/couchbaselabs/try-cb-java).
1639b41060SMichael Nitschinger
1739b41060SMichael NitschingerThe primary way to ask questions is through our official [Forums](http://forums.couchbase.com), although there is also a [stackoverflow tag](http://stackoverflow.com/questions/tagged/couchbase). You can also ask questions on `#couchbase` or `#libcouchbase` on IRC (freenode). Please file any issues you find or enhancements you want to request against our [JIRA](http://issues.couchbase.com/browse/JCBC) which we use for universal issue tracking.
182117ec8bSMichael Nitschinger
1939b41060SMichael Nitschinger## Quick Start ##
2039b41060SMichael NitschingerThe easiest way is to download the jar as well as its transitive dependencies (only 2) through maven:
2150de8557STugdual Grall
221ded28afSSimon Baslé
2339b41060SMichael Nitschinger```xml
2439b41060SMichael Nitschinger<dependency>
2539b41060SMichael Nitschinger    <groupId>com.couchbase.client</groupId>
2639b41060SMichael Nitschinger    <artifactId>java-client</artifactId>
276d0c16d6SMichael Nitschinger    <version>2.5.9</version>
2839b41060SMichael Nitschinger</dependency>
2939b41060SMichael Nitschinger```
302117ec8bSMichael Nitschinger
31c7124eb9SSimon BasléYou can find information to older versions as well as alternative downloads [here](http://developer.couchbase.com/server/other-products/release-notes-archives/java-sdk).
3239b41060SMichael Nitschinger
33c7124eb9SSimon BasléThe following code connects to the `Cluster`, opens a `Bucket`, stores a `Document`, retrieves it and prints out parts of the content.
342117ec8bSMichael Nitschinger
352117ec8bSMichael Nitschinger```java
362117ec8bSMichael Nitschinger// Create a cluster reference
372117ec8bSMichael NitschingerCouchbaseCluster cluster = CouchbaseCluster.create("");
382117ec8bSMichael Nitschinger
392117ec8bSMichael Nitschinger// Connect to the bucket and open it
402117ec8bSMichael NitschingerBucket bucket = cluster.openBucket("default");
412117ec8bSMichael Nitschinger
422117ec8bSMichael Nitschinger// Create a JSON document and store it with the ID "helloworld"
432117ec8bSMichael NitschingerJsonObject content = JsonObject.create().put("hello", "world");
4439b41060SMichael NitschingerJsonDocument inserted = bucket.upsert(JsonDocument.create("helloworld", content));
4550de8557STugdual Grall
462117ec8bSMichael Nitschinger// Read the document and print the "hello" field
472117ec8bSMichael NitschingerJsonDocument found = bucket.get("helloworld");
482117ec8bSMichael NitschingerSystem.out.println("Couchbase is the best database in the " + found.content().getString("hello"));
492117ec8bSMichael Nitschinger
502117ec8bSMichael Nitschinger// Close all buckets and disconnect
512117ec8bSMichael Nitschingercluster.disconnect();
522117ec8bSMichael Nitschinger```
532117ec8bSMichael Nitschinger
5439b41060SMichael NitschingerIf you want to perform a N1QL query against [Couchbase Server 4.0](http://www.couchbase.com/nosql-databases/couchbase-server) or later, you can do it like this:
55f122ff22SMatt Ingenthron
56ec02294cSMichael Nitschinger```java
57cf7537d1SSimon BasléN1qlQueryResult result = bucket.query(N1qlQuery.simple("SELECT DISTINCT(country) FROM `travel-sample` WHERE type = 'airline' LIMIT 10"));
58af0af11cSMichael Nitschinger
5939b41060SMichael Nitschingerfor (N1qlQueryRow row : result) {
6039b41060SMichael Nitschinger    System.out.println(row.value());
6139b41060SMichael Nitschinger}
62ec02294cSMichael Nitschinger```
6350de8557STugdual Grall
6439b41060SMichael NitschingerThis prints out the distinct countries for all airlines stored in the `travel-sample` bucket that comes with the server.
652117ec8bSMichael Nitschinger
66ff3a0db4SMichael NitschingerIf you want to learn more, check out the [Start Using the SDK](https://developer.couchbase.com/documentation/server/5.0/sdk/java/start-using-sdk.html) section in the official documentation.
67ec02294cSMichael Nitschinger
6839b41060SMichael Nitschinger## Contributing ##
692117ec8bSMichael Nitschinger
70cf7537d1SSimon BasléWe use Gerrit for our code review system. Please have a look at the extensive [`CONTRIBUTING.md`](CONTRIBUTING.md) for more details.
712117ec8bSMichael Nitschinger
7233918dfcSMichael NitschingerFeel free to reach out to the maintainers over the forums, IRC or email if you have further questions on contributing or get stuck along the way. We love contributions and want to help you get your change over the finish line - and you mentioned in the release notes!