org.lightcouch

Class CouchDbClientBase

java.lang.Object

org.lightcouch.CouchDbClientBase

Direct Known Subclasses:

CouchDbClient, CouchDbClientAndroid

public abstract class CouchDbClientBase
extends java.lang.Object

Contains a client Public API implementation.

See Also:

CouchDbClient, CouchDbClientAndroid

Field Summary

Fields

Modifier and Type	Field and Description
private java.net.URI	baseURI
private CouchDbContext	context
private java.net.URI	dbURI
private CouchDbDesign	design
private com.google.gson.Gson	gson
(package private) org.apache.http.HttpHost	host
(package private) org.apache.http.client.HttpClient	httpClient
(package private) static org.apache.commons.logging.Log	log

Constructor Summary

Constructors

Constructor and Description
CouchDbClientBase()
CouchDbClientBase(CouchDbConfig config)

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, boolean allOrNothing) 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.
CouchDbContext	context() Provides access to DB server APIs.
(package private) abstract org.apache.http.protocol.HttpContext	createContext()
(package private) abstract org.apache.http.client.HttpClient	createHttpClient(CouchDbProperties properties)
(package private) Response	delete(java.net.URI uri) Performs a HTTP DELETE request.
CouchDbDesign	design() Provides access to CouchDB Design Documents.
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 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.
(package private) java.io.InputStream	get(org.apache.http.client.methods.HttpGet httpGet) Performs a HTTP GET request.
(package private) java.io.InputStream	get(java.net.URI uri) Performs a HTTP GET request.
(package private) <T> T	get(java.net.URI uri, java.lang.Class<T> classType) Performs a HTTP GET request.
java.net.URI	getBaseUri()
java.net.URI	getDBUri()
com.google.gson.Gson	getGson()
private Response	getResponse(org.apache.http.HttpResponse response)
private java.util.List<Response>	getResponseList(org.apache.http.HttpResponse response)
(package private) org.apache.http.HttpResponse	head(java.net.URI uri) Performs a HTTP HEAD request.
private com.google.gson.Gson	initGson(com.google.gson.GsonBuilder gsonBuilder) Builds Gson and registers any required serializer/deserializer.
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) Invokes an Update Handler.
Response	post(java.lang.Object object) Saves an object in the database using HTTP POST request.
(package private) org.apache.http.HttpResponse	post(java.net.URI uri, java.lang.String json) Performs a HTTP POST request.
(package private) Response	put(java.net.URI uri, java.io.InputStream instream, java.lang.String contentType) Performs a HTTP PUT request, saves an attachment.
(package private) Response	put(java.net.URI uri, java.lang.Object object, boolean newEntity) Performs a HTTP PUT request, saves or updates a document.
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.
Replication	replication() Provides access to CouchDB replication APIs.
Replicator	replicator() Provides access to the replicator database.
Response	save(java.lang.Object object) 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.
private 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) Sets a GsonBuilder to create Gson instance.
(package private) abstract void	shutdown() Shuts down the connection manager used by this client instance.
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.
(package private) void	validate(org.apache.http.HttpResponse response) Validates a HTTP response; on error cases logs status and throws relevant exceptions.
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

Field Detail

log

static final org.apache.commons.logging.Log log

baseURI

private java.net.URI baseURI

dbURI

private java.net.URI dbURI

gson

private com.google.gson.Gson gson

context

private CouchDbContext context

design

private CouchDbDesign design

httpClient

final org.apache.http.client.HttpClient httpClient

host

final org.apache.http.HttpHost host

Constructor Detail

CouchDbClientBase

CouchDbClientBase()

CouchDbClientBase

CouchDbClientBase(CouchDbConfig config)

Method Detail

createHttpClient

abstract org.apache.http.client.HttpClient createHttpClient(CouchDbProperties properties)

Returns:

HttpClient instance for HTTP request execution.

createContext

abstract org.apache.http.protocol.HttpContext createContext()

Returns:

HttpContext instance for HTTP request execution.

shutdown

abstract void shutdown()

Shuts down the connection manager used by this client instance.

context

public CouchDbContext context()

Provides access to DB server APIs.

See Also:

CouchDbContext

design

public CouchDbDesign 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

replication

public Replication replication()

Provides access to CouchDB replication APIs.

See Also:

Replication

replicator

public Replicator replicator()

Provides access to the replicator database.

See Also:

Replicator

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.

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

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.

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,
                                     boolean allOrNothing)

Performs a Bulk Documents insert request.

Parameters:

objects - The List of objects.

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

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:

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

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

invokeUpdateHandler

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

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.

Use this method in particular when the docId contain special characters such as slashes (/).

 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.

query - The query parameters as Params.

Returns:

The output of the request.

executeRequest

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

Executes a HTTP request.

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

Parameters:

request - The HTTP request to execute.

Returns:

HttpResponse

syncDesignDocsWithDb

public void syncDesignDocsWithDb()

Synchronize all design documents with the database.

setGsonBuilder

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

Sets a GsonBuilder to create Gson instance.

Useful for registering custom serializers/deserializers, such as JodaTime classes.

getBaseUri

public java.net.URI getBaseUri()

Returns:

The base URI.

getDBUri

public java.net.URI getDBUri()

Returns:

The database URI.

getGson

public com.google.gson.Gson getGson()

Returns:

The Gson instance.

get

java.io.InputStream get(org.apache.http.client.methods.HttpGet httpGet)

Performs a HTTP GET request.

Returns:

InputStream

get

java.io.InputStream get(java.net.URI uri)

Performs a HTTP GET request.

Returns:

InputStream

get

<T> T get(java.net.URI uri,
          java.lang.Class<T> classType)

Performs a HTTP GET request.

Returns:

An object of type T

head

org.apache.http.HttpResponse head(java.net.URI uri)

Performs a HTTP HEAD request.

Returns:

HttpResponse

put

Response put(java.net.URI uri,
             java.lang.Object object,
             boolean newEntity)

Performs a HTTP PUT request, saves or updates a document.

Returns:

Response

put

Response put(java.net.URI uri,
             java.io.InputStream instream,
             java.lang.String contentType)

Performs a HTTP PUT request, saves an attachment.

Returns:

Response

post

org.apache.http.HttpResponse post(java.net.URI uri,
                                  java.lang.String json)

Performs a HTTP POST request.

Returns:

HttpResponse

delete

Response delete(java.net.URI uri)

Performs a HTTP DELETE request.

Returns:

Response

validate

void validate(org.apache.http.HttpResponse response)
       throws java.io.IOException

Validates a HTTP response; on error cases logs status and throws relevant exceptions.

Parameters:

response - The HTTP response.

Throws:

java.io.IOException

getResponse

private Response getResponse(org.apache.http.HttpResponse response)
                      throws CouchDbException

Parameters:

response - The HttpResponse

Returns:

Response

Throws:

CouchDbException

getResponseList

private java.util.List<Response> getResponseList(org.apache.http.HttpResponse response)
                                          throws CouchDbException

Parameters:

response - The HttpResponse

Returns:

Response

Throws:

CouchDbException

setEntity

private 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.

initGson

private com.google.gson.Gson initGson(com.google.gson.GsonBuilder gsonBuilder)

Builds Gson and registers any required serializer/deserializer.

Returns:

Gson instance