org.lightcouch

Class CouchDbClient

java.lang.Object

org.lightcouch.CouchDbClient

public final class CouchDbClient
extends java.lang.Object

Presents a client to a CouchDB database instance.

This is the main class to use to gain access to the various APIs defined by this client.

Usage Example:

Instantiating an instance of this class requires configuration options to be supplied. Properties files may be used for this purpose. See overloaded constructors for available options.

A typical example for creating an instance is by preparing a properties file named couchdb.properties and placing it in your application classpath:

 couchdb.name=my-db
 couchdb.createdb.if-not-exist=true
 couchdb.protocol=http
 couchdb.host=127.0.0.1
 couchdb.port=5984
 couchdb.username=
 couchdb.password=
 

Then construct a new instance using the default constructor:

 CouchDbClient dbClient = new CouchDbClient(); // looks for classpath:couchdb.properties
 // access the API here
 

Multiple client instances could be created to handle multiple database instances simultaneously in a thread-safe manner, typically one client for each database.

A client instance provides access to various APIs, accessible under several locations or contexts.

Document APIs are available directly under this instance:

  Foo foo = dbClient.find(Foo.class, "some-id");
 

Design documents API under the context design() CouchDbDesign contains usage example.

View APIs under the context view() View contains usage examples.

Change Notifications API under the context changes() see Changes for usage example.

Replication APIs under two contexts: replication() and replicator(), the latter supports the replicator database introduced with CouchDB v 1.1.0 Replication and Replicator provide usage examples.

Database APIs under the context context()

After completing usage of this client, it might be useful to shutdown it's underlying connection manager to ensure proper release of resources: dbClient.shutdown()

Constructor Summary

Constructors

Constructor and Description
CouchDbClient() Constructs a new instance of this class, expects a configuration file named couchdb.properties to be available in your application classpath.
CouchDbClient(CouchDbProperties properties) Constructs a new instance of this class.
CouchDbClient(java.lang.String configFileName) Constructs a new instance of this class.
CouchDbClient(java.lang.String dbName, boolean createDbIfNotExist, java.lang.String protocol, java.lang.String host, int port, java.lang.String username, java.lang.String password) Constructs a new instance of this class.

Method Summary

Modifier and Type	Method and Description
void	batch(java.lang.Object object) Saves the given object in a batch request.
java.util.List<Response>	bulk(java.util.List<?> objects, boolean allOrNothing) Performs a Bulk Documents request.
Changes	changes() Provides access to the Change Notifications API.
boolean	contains(java.lang.String id) Checks if the database contains a document given an id.
CouchDbContext	context() Provides access to the database APIs.
CouchDbDesign	design() Provides access to the database design documents API.
protected org.apache.http.HttpResponse	executeRequest(org.apache.http.client.methods.HttpRequestBase request) Executes a HTTP request.
<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 returns the result as an InputStream.
java.io.InputStream	find(java.lang.String id, java.lang.String rev) Finds a document given an id and revision, returns the result as InputStream.
<T> T	findAny(java.lang.Class<T> classType, java.lang.String uri) A General purpose find, that gives more control over the query.
java.net.URI	getBaseUri()
protected org.lightcouch.CouchDbConfig	getConfig()
java.net.URI	getDBUri()
com.google.gson.Gson	getGson()
java.lang.String	invokeUpdateHandler(java.lang.String updateHandlerUri, java.lang.String docId, java.lang.String query) Invokes an Update Handler.
Response	remove(java.lang.Object object) Removes an object from the database, the object must have the correct id and revision values.
Response	remove(java.lang.String id, java.lang.String rev) Removes a document from the database, given both an id and revision values.
Replication	replication() Provides access to the replication APIs.
Replicator	replicator() Provides access to the replicator database APIs.
Response	save(java.lang.Object object) Saves an object in the database.
Response	saveAttachment(java.io.InputStream instream, java.lang.String name, java.lang.String contentType) Saves an attachment under a new document with a generated UUID as the document id.
Response	saveAttachment(java.io.InputStream instream, java.lang.String name, java.lang.String contentType, java.lang.String docId, java.lang.String docRev) Saves an attachment under an existing document given both a document id and revision, or under a new document given only the document id.
protected void	setEntity(org.apache.http.client.methods.HttpEntityEnclosingRequestBase httpRequest, java.lang.String json) Sets a JSON String as a request entity.
void	setGsonBuilder(com.google.gson.GsonBuilder gsonBuilder) The supplied GsonBuilder is used to create a new Gson instance.
void	shutdown() Shuts down the connection manager used by this client instance.
void	syncDesignDocsWithDb() Synchronize all design documents on desk with the database.
Response	update(java.lang.Object object) Updates an object in the database, the object must have the correct id and revision values.
View	view(java.lang.String viewId) Provides access to the View APIs.

Methods inherited from class java.lang.Object

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

Constructor Detail

CouchDbClient

public CouchDbClient()

Constructs a new instance of this class, expects a configuration file named couchdb.properties to be available in your application classpath.

CouchDbClient

public CouchDbClient(java.lang.String configFileName)

Constructs a new instance of this class.

Parameters:

configFileName - The configuration file name.

CouchDbClient

public CouchDbClient(java.lang.String dbName,
                     boolean createDbIfNotExist,
                     java.lang.String protocol,
                     java.lang.String host,
                     int port,
                     java.lang.String username,
                     java.lang.String password)

Constructs a new instance of this class.

Parameters:

dbName - The database name.

createDbIfNotExist - To create a new database if it does not already exist.

protocol - The protocol to use (i.e http or https)

host - The database host address

port - The database listening port

username - The Username credential

password - The Password credential

CouchDbClient

public CouchDbClient(CouchDbProperties properties)

Constructs a new instance of this class.

Parameters:

properties - An object containing configuration properties.

See Also:

CouchDbProperties}

Method Detail

setGsonBuilder

public void setGsonBuilder(com.google.gson.GsonBuilder gsonBuilder)

The supplied GsonBuilder is used to create a new Gson instance. Useful for registering custom serializers/deserializers, for example JodaTime DateTime class.

context

public CouchDbContext context()

Provides access to the database APIs.

design

public CouchDbDesign design()

Provides access to the database design documents API.

view

public View view(java.lang.String viewId)

Provides access to the View APIs.

replication

public Replication replication()

Provides access to the replication APIs.

replicator

public Replicator replicator()

Provides access to the replicator database APIs.

changes

public Changes changes()

Provides access to the Change Notifications API.

syncDesignDocsWithDb

public void syncDesignDocsWithDb()

Synchronize all design documents on desk with the database.

Shorthand for CouchDbDesign.synchronizeAllWithDb()

This method might be used to sync design documents upon a client creation, eg. a Spring bean init-method.

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 to get.

rev - The document revision.

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)

A General purpose find, that gives more control over the query.

Unlike other finders, this method expects a fully formated and encoded URI to be supplied.

Parameters:

classType - The class of type T.

uri - The URI.

Returns:

An object of type T.

find

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

Finds a document and returns the result as an InputStream.

The stream should be properly closed after usage, as to avoid connection leaks.

Parameters:

id - The document id.

Returns:

The result of the request as an 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 an id and revision, returns the result as InputStream.

The stream should be properly closed after usage, as to avoid connection leaks.

Parameters:

id - The document id.

rev - The document revision.

Returns:

The result of the request as an InputStream

Throws:

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

contains

public boolean contains(java.lang.String id)

Checks if the database contains a document given an id.

Parameters:

id - The document id.

Returns:

true If the document is found, false otherwise.

save

public Response save(java.lang.Object object)

Saves an object in the database.

Parameters:

object - The object to save

Returns:

Response

Throws:

DocumentConflictException - If a conflict is detected during the save.

batch

public void batch(java.lang.Object object)

Saves the given object in a batch request.

Parameters:

object - The object to save.

bulk

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

Performs a Bulk Documents request.

Parameters:

objects - The List of objects.

allOrNothing - Indicated whether the request has all-or-nothing semantics.

Returns:

List<Response> Containing the resulted entries.

saveAttachment

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

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

To retrieve an attachment, see find(String).

Parameters:

instream - The InputStream holding the binary data.

name - The attachment name.

contentType - The attachment "Content-Type".

Returns:

Response

saveAttachment

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

Saves an attachment under an existing document given both a document id and revision, or under a new document given only the document id.

To retrieve an attachment, see find(String).

Parameters:

instream - 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

update

public Response update(java.lang.Object object)

Updates an object in the database, the object must have the correct id and revision values.

Parameters:

object - The object to update

Returns:

Response

Throws:

DocumentConflictException - If a conflict is detected during the update.

remove

public Response remove(java.lang.Object object)

Removes an object from the database, the object must have the correct id and revision values.

Parameters:

object - The object to remove

Returns:

Response

Throws:

NoDocumentException - If the document could not be found in the database.

remove

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

Removes a document from the database, given both an id and revision values.

Parameters:

id - The document id

rev - The document revision

Returns:

Response

Throws:

NoDocumentException - If the document could not be found in the database.

invokeUpdateHandler

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

Invokes an Update Handler.

Parameters:

updateHandlerUri - The Update Handler URI, in the format: designDocId/updateFunction

docId - The document id to update.

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

Returns:

The output of the request.

getDBUri

public java.net.URI getDBUri()

Returns:

The database URI.

getBaseUri

public java.net.URI getBaseUri()

Returns:

The base URI.

getGson

public com.google.gson.Gson getGson()

Returns:

The Gson instance.

shutdown

public void shutdown()

Shuts down the connection manager used by this client instance.

getConfig

protected org.lightcouch.CouchDbConfig getConfig()

executeRequest

protected org.apache.http.HttpResponse executeRequest(org.apache.http.client.methods.HttpRequestBase request)

Executes a HTTP request.

Parameters:

request - The HTTP request to execute.

Returns:

HttpResponse

setEntity

protected void setEntity(org.apache.http.client.methods.HttpEntityEnclosingRequestBase httpRequest,
                         java.lang.String json)

Sets a JSON String as a request entity.

Parameters:

httpRequest - The request to set entity.

json - The JSON String to set.