Code Monkey home page Code Monkey logo

java-cloudant's Introduction

Cloudant Java Client

Build Status Maven Central Javadocs

This is the official Cloudant library for Java.

Installation and Usage

Gradle:

dependencies {
    compile group: 'com.cloudant', name: 'cloudant-client', version: '2.6.2'
}

Gradle with optional okhttp-urlconnection dependency:

dependencies {
    compile group: 'com.cloudant', name: 'cloudant-client', version: '2.6.2'
    compile group: 'com.squareup.okhttp', name: 'okhttp-urlconnection', version: '2.7.5'
}

Maven:

<dependency>
  <groupId>com.cloudant</groupId>
  <artifactId>cloudant-client</artifactId>
  <version>2.6.2</version>
</dependency>

Maven with optional okhttp-urlconnection dependency:

<dependency>
  <groupId>com.cloudant</groupId>
  <artifactId>cloudant-client</artifactId>
  <version>2.6.2</version>
</dependency>

<dependency>
  <groupId>com.squareup.okhttp</groupId>
  <artifactId>okhttp-urlconnection</artifactId>
  <version>2.7.5</version>
</dependency>
Optional OkHttp dependency

HTTP requests to the database are made using java.net.HttpURLConnection. Adding the optional dependency for the okhttp-urlconnection changes the HttpURLConnection from the default JVM implementation to the OkHttp implementation. Note that to use OkHttp requires a minimum of Java 1.7.

The main use case that is supported by this optional dependency is configuration of connection pools on a per CloudantClient basis (see the javadoc for ClientBuilder.maxConnections). If the OkHttp dependency is available at runtime it will be used automatically. Not using OkHttp will result in a smaller application size.

Getting Started

This section contains a simple example of creating a com.cloudant.client.api.CloudantClient instance and interacting with Cloudant.

For further examples and more advanced use cases see the javadoc for the version you are using. The source code for the tests in this github project also contains many examples of API usage.

// Create a new CloudantClient instance for account endpoint example.cloudant.com
CloudantClient client = ClientBuilder.account("example")
                                     .username("exampleUser")
                                     .password("examplePassword")
                                     .build();

// Note: for Cloudant Local or Apache CouchDB use:
// ClientBuilder.url(new URL("yourCloudantLocalAddress.example"))
//              .username("exampleUser")
//              .password("examplePassword")
//              .build();

// Show the server version
System.out.println("Server Version: " + client.serverVersion());

// Get a List of all the databases this Cloudant account
List<String> databases = client.getAllDbs();
System.out.println("All my databases : ");
for ( String db : databases ) {
	System.out.println(db);
}

// Working with data

// Delete a database we created previously.
client.deleteDB("example_db");

// Create a new database.
client.createDB("example_db");

// Get a Database instance to interact with, but don't create it if it doesn't already exist
Database db = client.database("example_db", false);

// A Java type that can be serialized to JSON
public class ExampleDocument {
  private String _id = "example_id";
  private String _rev = null;
  private boolean isExample;

  public ExampleDocument(boolean isExample) {
    this.isExample = isExample;
  }

  public String toString() {
    return "{ id: " + _id + ",\nrev: " + _rev + ",\nisExample: " + isExample + "\n}";
  }
}

// Create an ExampleDocument and save it in the database
db.save(new ExampleDocument(true));
System.out.println("You have inserted the document");

// Get an ExampleDocument out of the database and deserialize the JSON into a Java type
ExampleDocument doc = db.find(ExampleDocument.class,"example_id");
System.out.println(doc);

Output:

Server version = 1.0.2
All my databases: example_db, stuff, scores
You have inserted the document.
{ id: example_id,
  rev: 1-6e4cb465d49c0368ac3946506d26335d,
  isExample: true
}

There is significantly more documentation, including additional code samples and explanations, in the javadoc. The first page you land on when following the javadoc link includes a table of contents with further links to help guide you to the documentation you need. To find the additional information be sure to scroll down past the auto-generated summary tables and do not overlook the package overviews.

Related documentation

Development

For information about contributing, building, and running tests see the CONTRIBUTING.md.

Using in Other Projects

The preferred approach for using java-cloudant in other projects is to use the Gradle or Maven dependency as described above.

License

Copyright 2014-2015 Cloudant, an IBM company.

Licensed under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at

http://www.apache.org/licenses/LICENSE-2.0.html

Unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. See the license for the specific language governing permissions and limitations under the license.

Issues

If you are a Cloudant customer please contact Cloudant support for help with any issues.

It is also possible to open issues here in github.

Caching, Encryption, and Compression

Caching data at the client, when it is appropriate for the application, can often improve performance considerably. In some cases, it may also be desirable to encrypt or compress data at the client. There is no built-in support for caching, encryption or compression at the client in java-cloudant. Other Java libraries that are not officially supported by Cloudant, but can provide these capabilities are:

java-cloudant's People

Contributors

ahmedyha avatar behrica avatar brynh avatar emlaver avatar esrose avatar ganeshkumarc avatar henryabra avatar hiranya avatar iddo avatar lightcouch avatar majido avatar mariobriggs avatar michaelwj avatar mikerhodes avatar rhyshort avatar ricellis avatar rnewson avatar sebastien-cote avatar seize-the-dave avatar snowch avatar srl295 avatar valery1707 avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.