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.
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 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.
|
| 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.
|
public CouchDbClient()
couchdb.properties to be available in your application classpath.public CouchDbClient(java.lang.String configFileName)
configFileName - The configuration file name.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)
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 addressport - The database listening portusername - The Username credentialpassword - The Password credentialpublic CouchDbClient(CouchDbProperties properties)
properties - An object containing configuration properties.CouchDbProperties}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.
public CouchDbContext context()
public CouchDbDesign design()
public View view(java.lang.String viewId)
public Replication replication()
public Replicator replicator()
public Changes changes()
public void syncDesignDocsWithDb()
Shorthand for CouchDbDesign.synchronizeAllWithDb()
This method might be used to sync design documents upon a client creation, eg. a Spring bean init-method.
public <T> T find(java.lang.Class<T> classType,
java.lang.String id)
T - Object type.classType - The class of type T.id - The document id.NoDocumentException - If the document is not found in the database.public <T> T find(java.lang.Class<T> classType,
java.lang.String id,
Params params)
T - Object type.classType - The class of type T.id - The document id.params - Extra parameters to append.NoDocumentException - If the document is not found in the database.public <T> T find(java.lang.Class<T> classType,
java.lang.String id,
java.lang.String rev)
T - Object type.classType - The class of type T.id - The document id to get.rev - The document revision.NoDocumentException - If the document is not found in the database.public <T> T findAny(java.lang.Class<T> classType,
java.lang.String uri)
Unlike other finders, this method expects a fully formated and encoded URI to be supplied.
classType - The class of type T.uri - The URI.public java.io.InputStream find(java.lang.String id)
Finds a document and returns the result as an InputStream.
id - The document id.InputStreamNoDocumentException - If the document is not found in the database.find(String, String)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.
id - The document id.rev - The document revision.InputStreamNoDocumentException - If the document is not found in the database.public boolean contains(java.lang.String id)
id - The document id.public Response save(java.lang.Object object)
object - The object to saveResponseDocumentConflictException - If a conflict is detected during the save.public void batch(java.lang.Object object)
object - The object to save.public java.util.List<Response> bulk(java.util.List<?> objects, boolean allOrNothing)
objects - The List of objects.allOrNothing - Indicated whether the request has all-or-nothing semantics.List<Response> Containing the resulted entries.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).
instream - The InputStream holding the binary data.name - The attachment name.contentType - The attachment "Content-Type".Responsepublic 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).
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.ResponseDocumentConflictExceptionpublic Response update(java.lang.Object object)
object - The object to updateResponseDocumentConflictException - If a conflict is detected during the update.public Response remove(java.lang.Object object)
object - The object to removeResponseNoDocumentException - If the document could not be found in the database.public Response remove(java.lang.String id, java.lang.String rev)
id - The document idrev - The document revisionResponseNoDocumentException - If the document could not be found in the database.public java.lang.String invokeUpdateHandler(java.lang.String updateHandlerUri,
java.lang.String docId,
java.lang.String query)
updateHandlerUri - The Update Handler URI, in the format: designDocId/updateFunctiondocId - The document id to update.query - The query string parameters, e.g, field=field1&value=value1public java.net.URI getDBUri()
public java.net.URI getBaseUri()
public com.google.gson.Gson getGson()
public void shutdown()
protected org.lightcouch.CouchDbConfig getConfig()
protected org.apache.http.HttpResponse executeRequest(org.apache.http.client.methods.HttpRequestBase request)
request - The HTTP request to execute.HttpResponseprotected void setEntity(org.apache.http.client.methods.HttpEntityEnclosingRequestBase httpRequest,
java.lang.String json)
httpRequest - The request to set entity.json - The JSON String to set.