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.
void	createPartitionedDB(java.lang.String dbName) Request to create a new partitioned 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.
com.cloudant.http.HttpConnection	executeRequest(com.cloudant.http.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.
MetaInformation	metaInformation() Get the welcome message metadata.
Replication	replication() Provides access to Cloudant replication APIs.
Replicator	replicator() Provides access to Cloudant replication APIs.
SchedulerDocsResponse.Doc	schedulerDoc(java.lang.String docId) Get replication document state for a given replication document ID.
SchedulerDocsResponse	schedulerDocs() Lists replication documents.
SchedulerJobsResponse	schedulerJobs() Lists replication jobs.
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

clone, equals, finalize, 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.

Note that if create is false and the database does not exist an instance will be returned, but the first operation on that instance will throw a NoDocumentException because the database does not exist.

Parameters:

name - name of database to access

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

Returns:

Database object

See Also:

Databases

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:

PreconditionFailedException - if a database with the same name already exists

See Also:

Databases - create

createPartitionedDB

public void createPartitionedDB(java.lang.String dbName)

Request to create a new partitioned database with the specified name. A partitioned database introduces the ability for a user to create logical groups of documents called partitions by providing a partition key with each document. Operations on the database, specifically querying, will be extended to take partition keys as part of the request in order to constrain the operation (e.g., result set) to a specific partition.

Parameters:

dbName - the database name

Throws:

PreconditionFailedException - if a database with the same name already exists

See Also:

Databases - create, Database.query(String, String, Class), Database.search(String, String), SettableViewParameters.Common.partition(String)

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 list of databases

serverVersion

public java.lang.String serverVersion()

Get the reported server version from the welcome message metadata.

Returns:

Cloudant server version.

See Also:

GET meta information about the cluster

metaInformation

public MetaInformation metaInformation()

Get the welcome message metadata.

Returns:

Welcome message metadata.

See Also:

GET meta information about the cluster

replication

public Replication replication()

Provides access to Cloudant replication APIs.

Returns:

Replication object for configuration and triggering

See Also:

Replication, Replication - the _replicate endpoint

replicator

public Replicator replicator()

Provides access to Cloudant replication APIs.

Returns:

Replicator object for interacting with the _replicator DB

See Also:

Replicator, Replication - the _replicator database

schedulerJobs

public SchedulerJobsResponse schedulerJobs()

Lists replication jobs. Includes replications created via /_replicate endpoint as well as those created from replication documents. Does not include replications which have completed or have failed to start because replication documents were malformed. Each job description will include source and target information, replication id, a history of recent event, and a few other things.

Returns:

All current replication jobs

schedulerDocs

public SchedulerDocsResponse schedulerDocs()

Lists replication documents. Includes information about all the documents, even in completed and failed states. For each document it returns the document ID, the database, the replication ID, source and target, and other information.

Returns:

All replication documents

schedulerDoc

public SchedulerDocsResponse.Doc schedulerDoc(java.lang.String docId)

Get replication document state for a given replication document ID.

Parameters:

docId - The replication document ID

Returns:

Replication document for docId

executeRequest

public com.cloudant.http.HttpConnection executeRequest(com.cloudant.http.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
 }
 
 

Note that whilst the request can be constructed for any URL the connection information (e.g. Cookie, BasicAuth etc) specified by this client will be added to the request before it is executed.

Parameters:

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

Returns:

HttpConnection that has been executed

Throws:

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.