com.cloudant.client.api

Class Database

java.lang.Object

com.cloudant.client.api.Database

public class Database
extends java.lang.Object

Contains a Database Public API implementation. Methods may throw a NoDocumentException if the database does not exist.

Since:

0.0.1

Method Summary

Modifier and Type	Method and Description
void	batch(java.lang.Object object) Saves a document with batch=ok query param.
java.util.List<Response>	bulk(java.util.List<?> objects) Performs a Bulk Documents insert request.
Changes	changes() Provides access to Change Notifications API.
boolean	contains(java.lang.String id) Checks if a document exist in the database.
void	createIndex(java.lang.String indexDefinition) create a new Index
void	createIndex(java.lang.String indexName, java.lang.String designDocName, java.lang.String indexType, IndexField[] fields) Create a new index
void	deleteIndex(java.lang.String indexName, java.lang.String designDocId) Delete an index
DbDesign	design() Provides access to CouchDB Design Documents.
void	ensureFullCommit() Requests the database commits any recent changes to disk.
<T> T	find(java.lang.Class<T> classType, java.lang.String id) Finds an Object of the specified type.
<T> T	find(java.lang.Class<T> classType, java.lang.String id, Params params) Finds an Object of the specified type.
<T> T	find(java.lang.Class<T> classType, java.lang.String id, java.lang.String rev) Finds an Object of the specified type.
java.io.InputStream	find(java.lang.String id) Finds a document and return the result as InputStream.
java.io.InputStream	find(java.lang.String id, java.lang.String rev) Finds a document given id and revision and returns the result as InputStream.
<T> T	findAny(java.lang.Class<T> classType, java.lang.String uri) This method finds any document given a URI.
<T> java.util.List<T>	findByIndex(java.lang.String selectorJson, java.lang.Class<T> classOfT) Find documents using an index
<T> java.util.List<T>	findByIndex(java.lang.String selectorJson, java.lang.Class<T> classOfT, FindByIndexOptions options) Find documents using an index
java.net.URI	getDBUri()
java.util.Map<java.lang.String,java.util.EnumSet<Permissions>>	getPermissions() Returns the Permissions of this database.
Shard	getShard(java.lang.String docId) Get info about the shard a document belongs to
java.util.List<Shard>	getShards() Get info about the shards in the database
DbInfo	info()
java.lang.String	invokeUpdateHandler(java.lang.String updateHandlerUri, java.lang.String docId, Params params) Invokes an Update Handler.
java.lang.String	invokeUpdateHandler(java.lang.String updateHandlerUri, java.lang.String docId, java.lang.String query) Deprecated. use invokeUpdateHandler(String, String, Params) instead.
java.util.List<Index>	listIndices() List all indices
Response	post(java.lang.Object object) Saves an object in the database using HTTP POST request.
Response	post(java.lang.Object object, int writeQuorum) Saves an object in the database using HTTP POST request with specificied write quorum
Response	remove(java.lang.Object object) Removes a document from the database.
Response	remove(java.lang.String id, java.lang.String rev) Removes a document from the database given both a document _id and _rev values.
Response	save(java.lang.Object object) Saves an object in the database, using HTTP PUT request.
Response	save(java.lang.Object object, int writeQuorum) Saves an object in the database, using HTTP PUT request.
Response	saveAttachment(java.io.InputStream in, java.lang.String name, java.lang.String contentType) Saves an attachment to a new document with a generated UUID as the document id.
Response	saveAttachment(java.io.InputStream in, java.lang.String name, java.lang.String contentType, java.lang.String docId, java.lang.String docRev) Saves an attachment to an existing document given both a document id and revision, or save to a new document given only the id, and rev as null.
Search	search(java.lang.String searchIndexId) Provides access to Cloudant Search APIs.
void	setPermissions(java.lang.String userNameorApikey, java.util.EnumSet<Permissions> permissions) Set permissions for a user/apiKey on this database.
void	syncDesignDocsWithDb() Synchronize all design documents with the database.
Response	update(java.lang.Object object) Updates an object in the database, the object must have the correct _id and _rev values.
Response	update(java.lang.Object object, int writeQuorum) Updates an object in the database, the object must have the correct _id and _rev values.
View	view(java.lang.String viewId) Provides access to CouchDB View APIs.

Methods inherited from class java.lang.Object

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

Method Detail

setPermissions

public void setPermissions(java.lang.String userNameorApikey,
                           java.util.EnumSet<Permissions> permissions)

Set permissions for a user/apiKey on this database.

Note this method is only applicable to databases that support the Cloudant authorization API such as Cloudant DBaaS. For unsupported databases consider using the /db/_security endpoint.

Parameters:

userNameorApikey -

permissions - permissions to grant

Throws:

java.lang.UnsupportedOperationException - if called on a database that does not provide the Cloudant authorization API

See Also:

Roles, Modifying permissions

getPermissions

public java.util.Map<java.lang.String,java.util.EnumSet<Permissions>> getPermissions()

Returns the Permissions of this database.

Note this method is only applicable to databases that support the Cloudant authorization API such as Cloudant DBaaS. For unsupported databases consider using the /db/_security endpoint.

Returns:

the map of userNames to their Permissions

Throws:

java.lang.UnsupportedOperationException - if called on a database that does not provide the Cloudant authorization API

See Also:

Roles, Viewing permissions

getShards

public java.util.List<Shard> getShards()

Get info about the shards in the database

Returns:

List of shards

getShard

public Shard getShard(java.lang.String docId)

Get info about the shard a document belongs to

Parameters:

docId - document ID

Returns:

Shard info

createIndex

public void createIndex(java.lang.String indexName,
                        java.lang.String designDocName,
                        java.lang.String indexType,
                        IndexField[] fields)

Create a new index

Parameters:

indexName - optional name of the index (if not provided one will be generated)

designDocName - optional name of the design doc in which the index will be created

indexType - optional, type of index (only "json" as of now)

fields - array of fields in the index

createIndex

public void createIndex(java.lang.String indexDefinition)

create a new Index

Parameters:

indexDefinition -

See Also:

index definition

findByIndex

public <T> java.util.List<T> findByIndex(java.lang.String selectorJson,
                                         java.lang.Class<T> classOfT)

Find documents using an index

Parameters:

selectorJson - JSON object describing criteria used to select documents. Is of the form "selector": {<your data here>}

classOfT - The class of Java objects to be returned

Returns:

List of classOfT objects

See Also:

selector syntax

findByIndex

public <T> java.util.List<T> findByIndex(java.lang.String selectorJson,
                                         java.lang.Class<T> classOfT,
                                         FindByIndexOptions options)

Find documents using an index

Parameters:

selectorJson - JSON object describing criteria used to select documents. Is of the form "selector": {<your data here>}

options - query Index options

classOfT - The class of Java objects to be returned

Returns:

List of classOfT objects

See Also:

selector syntax

listIndices

public java.util.List<Index> listIndices()

List all indices

Returns:

List of Index

deleteIndex

public void deleteIndex(java.lang.String indexName,
                        java.lang.String designDocId)

Delete an index

Parameters:

indexName - name of the index

designDocId - ID of the design doc

search

public Search search(java.lang.String searchIndexId)

Provides access to Cloudant Search APIs.

See Also:

Search

design

public DbDesign design()

Provides access to CouchDB Design Documents.

See Also:

CouchDbDesign

view

public View view(java.lang.String viewId)

Provides access to CouchDB View APIs.

See Also:

View

changes

public Changes changes()

Provides access to Change Notifications API.

See Also:

Changes

find

public <T> T find(java.lang.Class<T> classType,
                  java.lang.String id)

Finds an Object of the specified type.

Type Parameters:

T - Object type.

Parameters:

classType - The class of type T.

id - The document id.

Returns:

An object of type T.

Throws:

NoDocumentException - If the document is not found in the database.

find

public <T> T find(java.lang.Class<T> classType,
                  java.lang.String id,
                  Params params)

Finds an Object of the specified type.

Type Parameters:

T - Object type.

Parameters:

classType - The class of type T.

id - The document id.

params - Extra parameters to append.

Returns:

An object of type T.

Throws:

NoDocumentException - If the document is not found in the database.

find

public <T> T find(java.lang.Class<T> classType,
                  java.lang.String id,
                  java.lang.String rev)

Finds an Object of the specified type.

Type Parameters:

T - Object type.

Parameters:

classType - The class of type T.

id - The document _id field.

rev - The document _rev field.

Returns:

An object of type T.

Throws:

NoDocumentException - If the document is not found in the database.

findAny

public <T> T findAny(java.lang.Class<T> classType,
                     java.lang.String uri)

This method finds any document given a URI.

The URI must be URI-encoded.

Parameters:

classType - The class of type T.

uri - The URI as string.

Returns:

An object of type T.

find

public java.io.InputStream find(java.lang.String id)

Finds a document and return the result as InputStream.

Note: The stream must be closed after use to release the connection.

Parameters:

id - The document _id field.

Returns:

The result as InputStream

Throws:

NoDocumentException - If the document is not found in the database.

See Also:

find(String, String)

find

public java.io.InputStream find(java.lang.String id,
                                java.lang.String rev)

Finds a document given id and revision and returns the result as InputStream.

Note: The stream must be closed after use to release the connection.

Parameters:

id - The document _id field.

rev - The document _rev field.

Returns:

The result as InputStream

Throws:

NoDocumentException - If the document is not found in the database.

contains

public boolean contains(java.lang.String id)

Checks if a document exist in the database.

Parameters:

id - The document _id field.

Returns:

true If the document is found, false otherwise.

save

public Response save(java.lang.Object object)

Saves an object in the database, using HTTP PUT request.

If the object doesn't have an _id value, the code will assign a UUID as the document id.

Parameters:

object - The object to save

Returns:

Response

Throws:

DocumentConflictException - If a conflict is detected during the save.

save

public Response save(java.lang.Object object,
                     int writeQuorum)

Saves an object in the database, using HTTP PUT request.

If the object doesn't have an _id value, the code will assign a UUID as the document id.

Parameters:

object - The object to save

writeQuorum - the write Quorum

Returns:

Response

Throws:

DocumentConflictException - If a conflict is detected during the save.

post

public Response post(java.lang.Object object)

Saves an object in the database using HTTP POST request.

The database will be responsible for generating the document id.

Parameters:

object - The object to save

Returns:

Response

post

public Response post(java.lang.Object object,
                     int writeQuorum)

Saves an object in the database using HTTP POST request with specificied write quorum

The database will be responsible for generating the document id.

Parameters:

object - The object to save

writeQuorum - the write Quorum

Returns:

Response

batch

public void batch(java.lang.Object object)

Saves a document with batch=ok query param.

Parameters:

object - The object to save.

update

public Response update(java.lang.Object object)

Updates an object in the database, the object must have the correct _id and _rev values.

Parameters:

object - The object to update

Returns:

Response

Throws:

DocumentConflictException - If a conflict is detected during the update.

update

public Response update(java.lang.Object object,
                       int writeQuorum)

Updates an object in the database, the object must have the correct _id and _rev values.

Parameters:

object - The object to update

writeQuorum - the write Quorum

Returns:

Response

Throws:

DocumentConflictException - If a conflict is detected during the update.

remove

public Response remove(java.lang.Object object)

Removes a document from the database.

The object must have the correct _id and _rev values.

Parameters:

object - The document to remove as object.

Returns:

Response

Throws:

NoDocumentException - If the document is not found in the database.

remove

public Response remove(java.lang.String id,
                       java.lang.String rev)

Removes a document from the database given both a document _id and _rev values.

Parameters:

id - The document _id field.

rev - The document _rev field.

Returns:

Response

Throws:

NoDocumentException - If the document is not found in the database.

bulk

public java.util.List<Response> bulk(java.util.List<?> objects)

Performs a Bulk Documents insert request.

Parameters:

objects - The List of objects.

Returns:

List<Response> Containing the resulted entries.

saveAttachment

public Response saveAttachment(java.io.InputStream in,
                               java.lang.String name,
                               java.lang.String contentType)

Saves an attachment to a new document with a generated UUID as the document id.

To retrieve an attachment, see find(String).

Parameters:

in - The InputStream holding the binary data.

name - The attachment name.

contentType - The attachment "Content-Type".

Returns:

Response

saveAttachment

public Response saveAttachment(java.io.InputStream in,
                               java.lang.String name,
                               java.lang.String contentType,
                               java.lang.String docId,
                               java.lang.String docRev)

Saves an attachment to an existing document given both a document id and revision, or save to a new document given only the id, and rev as null.

To retrieve an attachment, see find(String).

Parameters:

in - The InputStream holding the binary data.

name - The attachment name.

contentType - The attachment "Content-Type".

docId - The document id to save the attachment under, or null to save under a new document.

docRev - The document revision to save the attachment under, or null when saving to a new document.

Returns:

Response

Throws:

DocumentConflictException

invokeUpdateHandler

@Deprecated
public java.lang.String invokeUpdateHandler(java.lang.String updateHandlerUri,
                                                        java.lang.String docId,
                                                        java.lang.String query)

Deprecated. use invokeUpdateHandler(String, String, Params) instead.

Invokes an Update Handler. String query = "field=foo&value=bar"; String output = dbClient.invokeUpdateHandler("designDoc/update1", "docId", query);

Parameters:

updateHandlerUri - The Update Handler URI, in the format: designDoc/update1

docId - The document id to update.

query - The query string parameters, e.g, field=field1&value=value1

Returns:

The output of the request.

invokeUpdateHandler

public java.lang.String invokeUpdateHandler(java.lang.String updateHandlerUri,
                                            java.lang.String docId,
                                            Params params)

Invokes an Update Handler.

 Params params = new Params()
        .addParam("field", "foo")
        .addParam("value", "bar");
 String output = dbClient.invokeUpdateHandler("designDoc/update1", "docId", params);
 

Parameters:

updateHandlerUri - The Update Handler URI, in the format: designDoc/update1

docId - The document id to update.

params - The query parameters as Params.

Returns:

The output of the request.

syncDesignDocsWithDb

public void syncDesignDocsWithDb()

Synchronize all design documents with the database.

getDBUri

public java.net.URI getDBUri()

Returns:

The database URI.

info

public DbInfo info()

Returns:

CouchDbInfo Containing the DB info.

ensureFullCommit

public void ensureFullCommit()

Requests the database commits any recent changes to disk.