Database (cloudant-client 2.2.0 API)

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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`java.util.List<Response>`	`bulk(java.util.List<?> objects)` Uses the `_bulk_docs` endpoint to insert multiple documents into the database in a single HTTP request.
`Changes`	`changes()` Provides access for interacting with the changes feed.
`boolean`	`contains(java.lang.String id)` Checks if a document exists in the database.
`void`	`createIndex(java.lang.String indexDefinition)` Create a new index from a JSON string
`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
`void`	`ensureFullCommit()` Requests the database commits any recent changes to disk.
`<T> T`	`find(java.lang.Class<T> classType, java.lang.String id)` Retrieve the document with the specified ID from the database and deserialize to an instance of the POJO of type T.
`<T> T`	`find(java.lang.Class<T> classType, java.lang.String id, Params params)` Retrieve the document with the specified ID from the database and deserialize to an instance of the POJO of type T.
`<T> T`	`find(java.lang.Class<T> classType, java.lang.String id, java.lang.String rev)` Retrieve the document with the specified ID at the specified revision from the database and deserialize to an instance of the POJO of type T.
`java.io.InputStream`	`find(java.lang.String id)` Finds the document with the specified document ID and returns it as an `InputStream`.
`java.io.InputStream`	`find(java.lang.String id, java.lang.String rev)` Finds the document with the specified document ID and revision and returns it 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
`AllDocsRequestBuilder`	`getAllDocsRequestBuilder()` Build a request for the _all_docs endpoint.
`java.net.URI`	`getDBUri()`
`DesignDocumentManager`	`getDesignDocumentManager()` Get a manager that has convenience methods for managing design documents.
`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.
`ViewRequestBuilder`	`getViewRequestBuilder(java.lang.String designDoc, java.lang.String viewName)`
`DbInfo`	`info()` Get information about this database.
`java.lang.String`	`invokeUpdateHandler(java.lang.String updateHandlerUri, java.lang.String docId, Params params)` Invokes an Update Handler.
`java.util.List<Index>`	`listIndices()` List all indices
`Response`	`post(java.lang.Object object)` Creates a document in the database using a HTTP `POST` request.
`Response`	`post(java.lang.Object object, int writeQuorum)` Creates a document in the database similarly to `post(Object)` but using a specific 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 the document from the database with the specified `_id` and `_rev` values.
`Response`	`save(java.lang.Object object)` Saves a document in the database.
`Response`	`save(java.lang.Object object, int writeQuorum)` Saves a document in the database similarly to `save(Object)` but using a specific write quorum.
`Response`	`saveAttachment(java.io.InputStream in, java.lang.String name, java.lang.String contentType)` Creates an attachment from the specified InputStream and a new document with a generated document ID.
`Response`	`saveAttachment(java.io.InputStream in, java.lang.String name, java.lang.String contentType, java.lang.String docId, java.lang.String docRev)` Creates or updates an attachment on the given document ID and revision.
`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.
`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 similarly to `update(Object)`, but specifying the write quorum.

Methods inherited from class java.lang.Object
equals, 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.
    
    Example usage to set read-only access for a new key on the "example" database:
```
 
 // generate an API key
 ApiKey key = client.generateApiKey();

 // get the "example" database
 Database db = client.database("example", false);

 // set read-only permissions
 db.setPermissions(key.getKey(), EnumSet.<Permissions>of(Permissions._reader));
 
 
```
    Parameters:
    
    userNameorApikey - the user or key to apply permissions to
    
    permissions - permissions to grant
    
    Throws:
    
    java.lang.UnsupportedOperationException - if called on a database that does not provide the Cloudant authorization API
    
    See Also:
    
    CloudantClient.generateApiKey(), 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
    
    See Also:
    
    _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
    
    See Also:
    
    _shards
  - createIndex
```
public void createIndex(java.lang.String indexName,
                        java.lang.String designDocName,
                        java.lang.String indexType,
                        IndexField[] fields)
```
    Create a new index
    Example usage creating an index that sorts ascending on name, then by year.
```
 
 db.createIndex("Person_name", "Person_name", null, new IndexField[]{
       new IndexField("Person_name",SortOrder.asc),
       new IndexField("Movie_year",SortOrder.asc)});
 
 
```
    Example usage creating an index that sorts ascending by year.
```
 
 db.createIndex("Movie_year", "Movie_year", null, new IndexField[]{
      new IndexField("Movie_year",SortOrder.asc)});
 
 
```
    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 from a JSON string
    
    Parameters:
    
    indexDefinition - String representation of the index definition JSON
    
    See Also:
    
    createIndex(String, String, String, IndexField[]), index definition
  - findByIndex
```
public <T> java.util.List<T> findByIndex(java.lang.String selectorJson,
                                         java.lang.Class<T> classOfT)
```
    Find documents using an index
    
    Type Parameters:
    
    T - the type of the Java object to be returned
    
    Parameters:
    
    selectorJson - String representation of a JSON object describing criteria used to select documents. For example "\"selector\": {<your data here>}".
    
    classOfT - The class of Java objects to be returned
    
    Returns:
    
    List of classOfT objects
    
    See Also:
    
    findByIndex(String, Class, FindByIndexOptions), 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
    Example usage to return the name and year of movies starring Alec Guinness since 1960 with the results sorted by year descending:
```
 
 List <Movie> movies = db.findByIndex("\"selector\": {
 \"Movie_year\": {\"$gt\": 1960}, \"Person_name\": \"Alec Guinness\"
 }",
 Movie.class,
 new FindByIndexOptions()
 .sort(new IndexField("Movie_year", SortOrder.desc))
 .fields("Movie_name").fields("Movie_year"));
 
 
```
    Type Parameters:
    
    T - the type of the Java object to be returned
    
    Parameters:
    
    selectorJson - String representation of a JSON object describing criteria used to select documents. For example "\"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
    Example usage:
```
 
 List <Index> indices = db.listIndices();
 
 
```
    Returns:
    
    List of Index objects
  - 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.
    
    Parameters:
    
    searchIndexId - the name of the index to search
    
    Returns:
    
    Search object for searching the index
    
    See Also:
    
    Search
  - getDesignDocumentManager
```
public DesignDocumentManager getDesignDocumentManager()
```
    Get a manager that has convenience methods for managing design documents.
    
    Returns:
    
    a DesignDocumentManager for this database
    
    See Also:
    
    DesignDocumentManager
  - getViewRequestBuilder
```
public ViewRequestBuilder getViewRequestBuilder(java.lang.String designDoc,
                                                java.lang.String viewName)
```
    Parameters:
    
    designDoc - containing the view
    
    viewName - the view name
    
    Returns:
    
    a builder to build view requests for the specified design document and view of this database
    
    See Also:
    
    Using views
  - getAllDocsRequestBuilder
```
public AllDocsRequestBuilder getAllDocsRequestBuilder()
```
    Build a request for the _all_docs endpoint.
    Example usage:
```
 
  getAllDocsRequestBuilder().build().getResponse();
 
 
```
    Returns:
    
    a request builder for the _all_docs endpoint of this database
  - changes
```
public Changes changes()
```
    Provides access for interacting with the changes feed.
    See the Changes API for examples.
    
    Returns:
    
    a Changes object for using the changes feed
    
    See Also:
    
    Changes, Databases - get changes
  - find
```
public <T> T find(java.lang.Class<T> classType,
                  java.lang.String id)
```
    Retrieve the document with the specified ID from the database and deserialize to an instance of the POJO of type T.
    
    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
    
    See Also:
    
    find(Class, String, String), Documents - read
  - find
```
public <T> T find(java.lang.Class<T> classType,
                  java.lang.String id,
                  Params params)
```
    Retrieve the document with the specified ID from the database and deserialize to an instance of the POJO of type T. Uses the additional parameters specified when making the GET request.
    Example usage to get inline attachments:
```
 
 Foo foo = db.find(Foo.class, "exampleId", new Params().attachments());
 String attachmentData = foo.getAttachments().get("attachment.txt").getData();
 
 
```
    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.
    
    See Also:
    
    Params, Documents - read
  - find
```
public <T> T find(java.lang.Class<T> classType,
                  java.lang.String id,
                  java.lang.String rev)
```
    Retrieve the document with the specified ID at the specified revision from the database and deserialize to an instance of the POJO of type T.
    Example usage:
```
 
     Foo foo = db.find(Foo.class, "exampleId", "1-12345exampleRev");
 
 
```
    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.
    
    See Also:
    
    Documents - read
  - 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.
    
    Example usage retrieving the Foo POJO with document ID "exampleId" from the database "exampleDb" in the "example" Cloudant account.
```
 
 Foo foo = db.findAny(Foo.class, "https://example.cloudant.com/exampleDb/exampleId");
 
 
```
    Type Parameters:
    
    T - the type of Java object to return
    
    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 the document with the specified document ID and returns it as an 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 the document with the specified document ID and revision and returns it as InputStream.
    Note: The stream must be closed after use to release the connection.
    
    Example usage:
```
 
 InputStream inputStream = null;
 try{
     inputStream = db.find("exampleId", "1-12345exampleRev");
     //do stuff with the stream
 } finally {
     //close the input stream
     inputStream.close();
 }
 
 
```
    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 at the specified revision
    
    See Also:
    
    Documents - read
  - contains
```
public boolean contains(java.lang.String id)
```
    Checks if a document exists 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 a document in the database.
    If the serialized object's JSON does not contain an _id field, then a UUID will be generated for the document ID.
    
    Example of inserting a JsonObject into the database:
```
 
 JsonObject json = new JsonObject();
 json.addProperty("_id", "test-doc-id-2");
 json.add("json-array", new JsonArray());
 Response response = db.save(json);
 
 
```
    Example of inserting a POJO into the database:
```
 
 Foo foo = new Foo();
 Response response = db.save(foo);
 
 
```
    Example of inserting a Map into the database:
```
 
 Map<String, Object> map = new HashMap<>();
 map.put("_id", "test-doc-id-1");
 map.put("title", "test-doc");
 Response response = db.save(map);
 
 
```
    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 a document in the database similarly to save(Object) but using a specific write quorum.
    
    Parameters:
    
    object - the object to save
    
    writeQuorum - the write quorum
    
    Returns:
    
    Response
    
    Throws:
    
    DocumentConflictException - If a conflict is detected during the save.
    
    See Also:
    
    save(Object), Documents - quorum
  - post
```
public Response post(java.lang.Object object)
```
    Creates a document in the database using a HTTP POST request.
    If the serialized object's JSON does not contain an _id field, then the server will generate a document ID.
    
    Example of creating a document in the database for a POJO:
```
 
 Foo foo = new Foo();
 Response response = db.post(foo);
 
 
```
    Parameters:
    
    object - The object to save
    
    Returns:
    
    Response
    
    See Also:
    
    Documents - create
  - post
```
public Response post(java.lang.Object object,
                     int writeQuorum)
```
    Creates a document in the database similarly to post(Object) but using a specific write quorum.
    
    Parameters:
    
    object - The object to save
    
    writeQuorum - the write Quorum
    
    Returns:
    
    Response
    
    See Also:
    
    post(Object), Documents - quorum
  - update
```
public Response update(java.lang.Object object)
```
    Updates an object in the database, the object must have the correct _id and _rev values.
    Example usage:
```
 
 //get a Bar object from the database
 Bar bar = db.find(Bar.class, "exampleId");
 //change something about bar
 bar.setSomeProperty(true);
 //now update the remote Bar
 Response responseUpdate = db.update(bar);
 
 
```
    Parameters:
    
    object - the object to update
    
    Returns:
    
    Response
    
    Throws:
    
    DocumentConflictException - if a conflict is detected during the update.
    
    See Also:
    
    Documents - update
  - update
```
public Response update(java.lang.Object object,
                       int writeQuorum)
```
    Updates an object in the database similarly to update(Object), but specifying the write quorum.
    
    Parameters:
    
    object - the object to update
    
    writeQuorum - the write quorum
    
    Returns:
    
    Response
    
    Throws:
    
    DocumentConflictException - if a conflict is detected during the update.
    
    See Also:
    
    update(Object), Documents - quorum
  - remove
```
public Response remove(java.lang.Object object)
```
    Removes a document from the database.
    The object must have the correct _id and _rev values.
    
    Example usage:
```
 
 //get a Bar object from the database
 Bar bar = db.find(Bar.class, "exampleId");
 //now remove the remote Bar
 Response response = db.remove(bar);
 
 
```
    Parameters:
    
    object - the document to remove as an object
    
    Returns:
    
    Response
    
    Throws:
    
    NoDocumentException - If the document is not found in the database.
    
    See Also:
    
    Documents - delete
  - remove
```
public Response remove(java.lang.String id,
                       java.lang.String rev)
```
    Removes the document from the database with the specified _id and _rev values.
    Example usage:
```
 
 Response response = db.remove("exampleId", "1-12345exampleRev");
 
 
```
    Parameters:
    
    id - the document _id field
    
    rev - the document _rev field
    
    Returns:
    
    Response
    
    Throws:
    
    NoDocumentException - If the document is not found in the database.
    
    See Also:
    
    Documents - delete
  - bulk
```
public java.util.List<Response> bulk(java.util.List<?> objects)
```
    Uses the _bulk_docs endpoint to insert multiple documents into the database in a single HTTP request.
    Example usage:
```
 
 //create a list
 List<Object> newDocs = new ArrayList<Object>();
 //add some objects to the list
 newDocs.add(new Foo());
 newDocs.add(new JsonObject());
 //use the bulk insert
 List<Response> responses = db.bulk(newDocs);
 
 
```
    Parameters:
    
    objects - the List of objects
    
    Returns:
    
    List<Response> one per object
    
    See Also:
    
    Documents - bulk operations
  - saveAttachment
```
public Response saveAttachment(java.io.InputStream in,
                               java.lang.String name,
                               java.lang.String contentType)
```
    Creates an attachment from the specified InputStream and a new document with a generated document ID.
    Example usage:
```
 
 byte[] bytesToDB = "binary data".getBytes();
 ByteArrayInputStream bytesIn = new ByteArrayInputStream(bytesToDB);
 Response response = db.saveAttachment(bytesIn, "foo.txt", "text/plain");
 
 
```
    To retrieve an attachment, see find(Class, String, Params)
    Parameters:
    
    in - The InputStream providing the binary data.
    
    name - The attachment name.
    
    contentType - The attachment "Content-Type".
    
    Returns:
    
    Response
    
    See Also:
    
    Attachments
  - saveAttachment
```
public Response saveAttachment(java.io.InputStream in,
                               java.lang.String name,
                               java.lang.String contentType,
                               java.lang.String docId,
                               java.lang.String docRev)
```
    Creates or updates an attachment on the given document ID and revision.
    If docId and docRev are null a new document will be created.
    
    Example usage:
```
 
 byte[] bytesToDB = "binary data".getBytes();
 ByteArrayInputStream bytesIn = new ByteArrayInputStream(bytesToDB);
 Response response = db.saveAttachment(bytesIn, "foo.txt", "text/plain","exampleId","3-rev");
 
 
```
    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(Class, String, Params)
    Parameters:
    
    in - The InputStream providing 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 - if the attachment cannot be saved because of a conflict
    
    See Also:
    
    Attachments
  - invokeUpdateHandler
```
public java.lang.String invokeUpdateHandler(java.lang.String updateHandlerUri,
                                            java.lang.String docId,
                                            Params params)
```
    Invokes an Update Handler.
    Example usage:
```
 
 final String newValue = "foo bar";
 Params params = new Params()
         .addParam("field", "title")
         .addParam("value", newValue);
 String output = db.invokeUpdateHandler("example/example_update", "exampleId", params);

 
 
```
```
 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. If no id is provided, then a document will be created.
    
    params - The query parameters as Params.
    
    Returns:
    
    The output of the request.
    
    See Also:
    
    Design documents - update handlers
  - getDBUri
```
public java.net.URI getDBUri()
```
    Returns:
    
    The database URI.
  - info
```
public DbInfo info()
```
    Get information about this database.
    
    Returns:
    
    DbInfo encapsulating the database info
    
    See Also:
    
    Databases - read
  - ensureFullCommit
```
public void ensureFullCommit()
```
    Requests the database commits any recent changes to disk.
    
    See Also:
    
    CouchDB _ensure_full_commit

Class Database

Method Summary

Methods inherited from class java.lang.Object

Method Detail

setPermissions

getPermissions

getShards

getShard

createIndex

createIndex

findByIndex

findByIndex

listIndices

deleteIndex

search

getDesignDocumentManager

getViewRequestBuilder

getAllDocsRequestBuilder

changes

find

find

find

findAny

find

find

contains

save

save

post

post

update

update

remove

remove

bulk

saveAttachment

saveAttachment

invokeUpdateHandler

getDBUri

info

ensureFullCommit