com.cloudant.client.api

Class CloudantClient

java.lang.Object

com.cloudant.client.api.CloudantClient

public class CloudantClient
extends java.lang.Object

Exposes the Cloudant client API

This class is the main object to use to gain access to the Cloudant APIs. Instances of CloudantClient are created using a ClientBuilder. Once created a CloudantClient is immutable and safe to access from multiple threads.

Usage Examples:

Create a new Cloudant client instance

CloudantClient client = ClientBuilder.account CloudantClient("mycloudantaccount","myusername", "mypassword");

Client use of the API

• Server APIs accessed by the client directly e.g.:

  client.getAllDbs()

• DB is accessed by getting the Database from the client e.g.:

  Database db = client.database("customers",false);

• Document CRUD APIs accessed from the Database e.g.:

  db.find(Foo.class, "doc-id")

Cloudant Query

• Create an index Database.createIndex(String, String, String, IndexField[]) e.g.:

  db.createIndex("Person_name", "Person_name_design_doc", "json", new IndexField[] { new IndexField ("Person_name",SortOrder.asc)})

• Find using an index Database.findByIndex(String, Class) e.g.:

  db.findByIndex(" \"selector\": { \"Person_name\": \"Alec Guinness\" }", Movie.class)}

• Delete an index Database.deleteIndex(String, String) e.g.:

  db.deleteIndex("Person_name", "Person_name_design_doc")

Cloudant Search

db.search("views101/animals")

View APIs

com.cloudant.client.api.views

Change Notifications

db.changes()

Design Documents

db.getDesignDocumentManager()

Replication

Replication account.replication() and account.replicator()

Since:

0.0.1

Method Summary

Modifier and Type	Method and Description
void	createDB(java.lang.String dbName) Request to create a new database with the specified name.
Database	database(java.lang.String name, boolean create) Get a database reference for the database with the specified name.
void	deleteDB(java.lang.String dbName) Request to delete the database with the specified name.
HttpConnection	executeRequest(HttpConnection request) Executes a HTTP request.
ApiKey	generateApiKey() Use the authorization feature to generate new API keys to access your data.
java.util.List<Task>	getActiveTasks() Get the list of active tasks from the server.
java.util.List<java.lang.String>	getAllDbs() List all the databases on the server for the Cloudant account.
java.net.URI	getBaseUri()
com.google.gson.Gson	getGson()
Membership	getMembership() Get the list of all nodes and the list of active nodes in the cluster.
Replication	replication() Provides access to Cloudant replication APIs.
Replicator	replicator() Provides access to Cloudant replication APIs.
java.lang.String	serverVersion() Get the reported server version from the welcome message metadata.
void	shutdown() Shuts down the connection manager used by this client instance.
java.util.List<java.lang.String>	uuids(long count) Request a list of generated UUIDs from the Cloudant server.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

generateApiKey

public ApiKey generateApiKey()

Use the authorization feature to generate new API keys to access your data. An API key is similar to a username/password pair for granting others access to your data.

Example usage:

 
 ApiKey key = client.generateApiKey();
 System.out.println(key);
 
 

Example output:

  key: isdaingialkyciffestontsk password: XQiDHmwnkUu4tknHIjjs2P64
 

Returns:

the generated key and password

See Also:

Database.setPermissions(String, EnumSet)

getActiveTasks

public java.util.List<Task> getActiveTasks()

Get the list of active tasks from the server.

Returns:

List of tasks

See Also:

Active tasks

getMembership

public Membership getMembership()

Get the list of all nodes and the list of active nodes in the cluster.

Returns:

Membership object encapsulating lists of all nodes and the cluster nodes

See Also:

_membership

database

public Database database(java.lang.String name,
                         boolean create)

Get a database reference for the database with the specified name.

Parameters:

name - name of database to access

create - flag indicating whether to create the database if it does not exist

Returns:

Database object

Throws:

com.cloudant.client.org.lightcouch.NoDocumentException - if the database does not exist and create was false

See Also:

Databases - read

deleteDB

public void deleteDB(java.lang.String dbName)

Request to delete the database with the specified name.

Parameters:

dbName - the database name

See Also:

Databases - delete

createDB

public void createDB(java.lang.String dbName)

Request to create a new database with the specified name.

Parameters:

dbName - the database name

Throws:

com.cloudant.client.org.lightcouch.PreconditionFailedException - if a database with the same name already exists

See Also:

Databases - create

getBaseUri

public java.net.URI getBaseUri()

Returns:

The base URI.

getAllDbs

public java.util.List<java.lang.String> getAllDbs()

List all the databases on the server for the Cloudant account.

Returns:

List of the names of all the databases

See Also:

Databases - get databases

serverVersion

public java.lang.String serverVersion()

Get the reported server version from the welcome message metadata.

Returns:

Cloudant server version.

See Also:

Welcome message

replication

public Replication replication()

Provides access to Cloudant replication APIs.

Returns:

Replication object for configuration and triggering

See Also:

Replication, Replication - _replicate

replicator

public Replicator replicator()

Provides access to Cloudant replication APIs.

Returns:

Replicator object for interacting with the _replicator DB

See Also:

Replicator, Replication - _replicator

executeRequest

public HttpConnection executeRequest(HttpConnection request)

Executes a HTTP request. This method provides a mechanism to perform operations not currently available in the client API.

Note: Streams obtained from the HttpConnection must be closed after use to release the connection.

 
 HttpConnection response = account.executeRequest(Http.GET(new URL(account.getBaseUri() +
         "/aNewAPI")));
 if (response.getConnection().getResponseCode() == HttpURLConnection.HTTP_OK) {
     InputStream stream = response.responseAsInputStream();
     //process stream
 }
 
 

Parameters:

request - The HTTP request to execute, obtained from Http.

Returns:

HttpConnection that has been executed

Throws:

com.cloudant.client.org.lightcouch.CouchDbException - for error HTTP status codes or if there is an IOException

shutdown

public void shutdown()

Shuts down the connection manager used by this client instance.

uuids

public java.util.List<java.lang.String> uuids(long count)

Request a list of generated UUIDs from the Cloudant server.

Parameters:

count - the number of UUIDs

Returns:

a List of UUID Strings

See Also:

_uuids

getGson

public com.google.gson.Gson getGson()

Returns:

The Gson instance.