org.ektorp
Interface CouchDbConnector

All Known Implementing Classes:

StdCouchDbConnector

public interface CouchDbConnector

Primary interface for working with Objects mapped as documents in CouchDb. Mapped Objects must have getters and setters for id and revision. public String getId() public void setId(String s) public String getRevision() public void setRevision(String s) Reflection is used to access these methods.

Author:

henrik lundgren

Method Summary

void	addToBulkBuffer(java.lang.Object o) Add the object to the bulk buffer attached to the executing thread.
java.util.List<DocumentChange>	changes(ChangesCommand cmd) Queries the database for changes.
ChangesFeed	changesFeed(ChangesCommand cmd) Sets up a continuous changes feed.
void	cleanupViews() View indexes on disk are named after their MD5 hash of the view definition.
void	clearBulkBuffer() Clears the bulk buffer attached the the executing thread.
void	compact() Compaction compresses the database file by removing unused sections created during updates.
void	compactViews(java.lang.String designDocumentId) This compacts the view index from the current version of the design document.
boolean	contains(java.lang.String id) Check if the database contains a document.
void	create(java.lang.Object o) Creates the Object as a document in the database.
void	create(java.lang.String id, org.codehaus.jackson.JsonNode json)
java.lang.String	createAttachment(java.lang.String docId, AttachmentInputStream data) Creates both the document and the attachment
java.lang.String	createAttachment(java.lang.String docId, java.lang.String revision, AttachmentInputStream data) Adds an attachment to the specified document id.
void	createDatabaseIfNotExists() Creates a database on the configured path if it does not exists.
java.lang.String	delete(java.lang.Object o) Deletes the Object in the database.
java.lang.String	delete(java.lang.String id, java.lang.String revision) Deletes the document in the database.
java.lang.String	deleteAttachment(java.lang.String docId, java.lang.String revision, java.lang.String attachmentId)
java.util.List<DocumentOperationResult>	executeAllOrNothing(java.util.Collection<?> objects) Creates, updates or deletes all objects in the supplied collection.
java.util.List<DocumentOperationResult>	executeBulk(java.util.Collection<?> objects) Creates, updates or deletes all objects in the supplied collection.
java.util.List<DocumentOperationResult>	flushBulkBuffer() Sends the bulk buffer attached the the executing thread to the database (through a executeBulk call).
<T> T	get(java.lang.Class<T> c, java.lang.String id)
<T> T	get(java.lang.Class<T> c, java.lang.String id, java.lang.String rev)
java.util.List<java.lang.String>	getAllDocIds()
java.io.InputStream	getAsStream(java.lang.String id) Please note that the stream has to be closed after usage, otherwise http connection leaks will occur and the system will eventually hang due to connection starvation.
java.io.InputStream	getAsStream(java.lang.String id, java.lang.String rev) Please note that the stream has to be closed after usage, otherwise http connection leaks will occur and the system will eventually hang due to connection starvation.
AttachmentInputStream	getAttachment(java.lang.String id, java.lang.String attachmentId) Reads an attachment from the database.
HttpClient	getConnection() Convenience method for accessing the underlying HttpClient.
java.lang.String	getDatabaseName()
DbInfo	getDbInfo() Provides meta information about this database.
DesignDocInfo	getDesignDocInfo(java.lang.String designDocId) Obtains information about a given design document, including the index, index size and current status of the design document and associated index information.
int	getRevisionLimit() Revision limit defines a upper bound of document revisions which CouchDB keeps track of
java.util.List<Revision>	getRevisions(java.lang.String id)
<T> T	getWithConflicts(java.lang.Class<T> c, java.lang.String id) Will load the document with any conflicts included.
java.lang.String	path()
java.io.InputStream	queryForStream(ViewQuery query)
ViewResult	queryView(ViewQuery query)
<T> java.util.List<T>	queryView(ViewQuery query, java.lang.Class<T> type) This method requires the view result values to be document ids or documents : If the value is a document id, then the document is fetched from couchDB.
ReplicationStatus	replicateFrom(java.lang.String source) Replicate the content in the source database into this database.
ReplicationStatus	replicateFrom(java.lang.String source, java.util.Collection<java.lang.String> docIds) Replicate the content in the source database into this database.
ReplicationStatus	replicateTo(java.lang.String target) Replicate the content in this database into the specified target database.
ReplicationStatus	replicateTo(java.lang.String target, java.util.Collection<java.lang.String> docIds) Replicate the content in this database into the specified target database.
void	setRevisionLimit(int limit)
void	update(java.lang.Object o) Updates the document.

Method Detail

create

void create(java.lang.String id,
            org.codehaus.jackson.JsonNode json)

Parameters:

id -

json - The document in the form of an Jackson JsonNode.

Throws:

UpdateConflictException - if there was an update conflict.

create

void create(java.lang.Object o)

Creates the Object as a document in the database. If the id is not set it will be generated by the database. The Object's revision field will be updated through the setRevision(String s) method.

Parameters:

o -

Throws:

UpdateConflictException - if there was an update conflict.

update

void update(java.lang.Object o)

Updates the document. The Object's revision field will be updated through the setRevision(String s) method.

Parameters:

o -

Throws:

UpdateConflictException - if there was an update conflict.

delete

java.lang.String delete(java.lang.Object o)

Deletes the Object in the database.

Parameters:

o -

Returns:

the revision of the deleted document

Throws:

UpdateConflictException - if there was an update conflict.

delete

java.lang.String delete(java.lang.String id,
                        java.lang.String revision)

Deletes the document in the database.

Parameters:

id -

revision -

Returns:

the revision of the deleted document.

Throws:

UpdateConflictException - if there was an update conflict.

get

<T> T get(java.lang.Class<T> c,
          java.lang.String id)

Type Parameters:

T -

Parameters:

c - the target class to map to.

id - the id of the document in the database.

Returns:

the document mapped as the specified class.

Throws:

DocumentNotFoundException - if the document was not found.

get

<T> T get(java.lang.Class<T> c,
          java.lang.String id,
          java.lang.String rev)

Type Parameters:

T -

Parameters:

c - the target class to map to.

id - the id of the document in the database.

rev - of the object.

Returns:

the document mapped as the specified class.

Throws:

DocumentNotFoundException - if the document was not found.

getWithConflicts

<T> T getWithConflicts(java.lang.Class<T> c,
                       java.lang.String id)

Will load the document with any conflicts included.

Type Parameters:

T -

Parameters:

c - the target class to map to.

id - the id of the document in the database.

Returns:

the document mapped as the specified class.

Throws:

DocumentNotFoundException - if the document was not found.

contains

boolean contains(java.lang.String id)

Check if the database contains a document.

Parameters:

id -

Returns:

true if a document with the id exists in the database

getAsStream

java.io.InputStream getAsStream(java.lang.String id)

Please note that the stream has to be closed after usage, otherwise http connection leaks will occur and the system will eventually hang due to connection starvation.

Parameters:

id -

Returns:

the document as raw json in an InputStream, don't forget to close the stream when finished.

Throws:

DocumentNotFoundException - if the document was not found.

getAsStream

java.io.InputStream getAsStream(java.lang.String id,
                                java.lang.String rev)

Please note that the stream has to be closed after usage, otherwise http connection leaks will occur and the system will eventually hang due to connection starvation.

Parameters:

id -

rev -

Returns:

the document as raw json in an InputStream, don't forget to close the stream when finished.

Throws:

DocumentNotFoundException - if the document was not found.

getRevisions

java.util.List<Revision> getRevisions(java.lang.String id)

Parameters:

id -

Returns:

Throws:

DocumentNotFoundException - if the document was not found.

getAttachment

AttachmentInputStream getAttachment(java.lang.String id,
                                    java.lang.String attachmentId)

Reads an attachment from the database. Please note that the stream has to be closed after usage, otherwise http connection leaks will occur and the system will eventually hang due to connection starvation.

Parameters:

id -

attachmentId -

Returns:

the attachment in the form of an AttachmentInputStream.

Throws:

DocumentNotFoundException - if the document was not found.

createAttachment

java.lang.String createAttachment(java.lang.String docId,
                                  AttachmentInputStream data)

Creates both the document and the attachment

Parameters:

docId -

a - - the data to be saved as an attachment

Returns:

revision of the created attachment document

Throws:

UpdateConflictException - if there was an update conflict.

createAttachment

java.lang.String createAttachment(java.lang.String docId,
                                  java.lang.String revision,
                                  AttachmentInputStream data)

Adds an attachment to the specified document id.

Parameters:

docId -

revision -

a - - the data to be saved as an attachment

Returns:

the new revision of the document

Throws:

UpdateConflictException - if there was an update conflict.

deleteAttachment

java.lang.String deleteAttachment(java.lang.String docId,
                                  java.lang.String revision,
                                  java.lang.String attachmentId)

Parameters:

docId -

revision -

attachmentId -

Returns:

the new revision of the document

Throws:

UpdateConflictException - if there was an update conflict.

getAllDocIds

java.util.List<java.lang.String> getAllDocIds()

Returns:

all document ids in the database including design document ids.

queryView

<T> java.util.List<T> queryView(ViewQuery query,
                                java.lang.Class<T> type)

This method requires the view result values to be document ids or documents :

• If the value is a document id, then the document is fetched from couchDB.
• If the value is a document, then it is used directly for unmarshalling.

{"_id":"_design/ExampleDoc", "views":{ "all": {"map": "function(doc) { emit(null, doc._id);}"}, "by_name": {"map": "function(doc) { emit(doc.name, doc._id);}"} // emit doc id "by_author": {"map": "function(doc) { emit(doc.author, doc);}"} // emit doc } }

Type Parameters:

T -

Parameters:

query -

type - the type to map the result to

Returns:

the view result mapped as the specified class.

queryView

ViewResult queryView(ViewQuery query)

Parameters:

query -

Returns:

queryForStream

java.io.InputStream queryForStream(ViewQuery query)

Parameters:

query -

Returns:

the view result as a raw InputStream.

createDatabaseIfNotExists

void createDatabaseIfNotExists()

Creates a database on the configured path if it does not exists.

getDatabaseName

java.lang.String getDatabaseName()

Returns:

name

path

java.lang.String path()

Returns:

getConnection

HttpClient getConnection()

Convenience method for accessing the underlying HttpClient. Preferably used wrapped in a org.ektorp.http.RestTemplate.

Returns:

getDbInfo

DbInfo getDbInfo()

Provides meta information about this database.

Returns:

getDesignDocInfo

DesignDocInfo getDesignDocInfo(java.lang.String designDocId)

Obtains information about a given design document, including the index, index size and current status of the design document and associated index information.

Parameters:

designDocId -

Returns:

compact

void compact()

Compaction compresses the database file by removing unused sections created during updates. This call is non-blocking, a compaction background task will be created on the CouchDB instance.

compactViews

void compactViews(java.lang.String designDocumentId)

This compacts the view index from the current version of the design document. This call is non-blocking, a compaction background task will be created on the CouchDB instance.

Parameters:

designDocumentId -

cleanupViews

void cleanupViews()

View indexes on disk are named after their MD5 hash of the view definition. When you change a view, old indexes remain on disk. To clean up all outdated view indexes (files named after the MD5 representation of views, that does not exist anymore) you can trigger a view cleanup

getRevisionLimit

int getRevisionLimit()

Revision limit defines a upper bound of document revisions which CouchDB keeps track of

Returns:

setRevisionLimit

void setRevisionLimit(int limit)

replicateFrom

ReplicationStatus replicateFrom(java.lang.String source)

Replicate the content in the source database into this database.

Parameters:

source - database

Returns:

ReplicationStatus

replicateFrom

ReplicationStatus replicateFrom(java.lang.String source,
                                java.util.Collection<java.lang.String> docIds)

Replicate the content in the source database into this database. Replication is restricted to the specified document ids.

Parameters:

source - database

docIds -

Returns:

ReplicationStatus

replicateTo

ReplicationStatus replicateTo(java.lang.String target)

Replicate the content in this database into the specified target database. The target must exist.

Parameters:

target - database

Returns:

ReplicationStatus

replicateTo

ReplicationStatus replicateTo(java.lang.String target,
                              java.util.Collection<java.lang.String> docIds)

Replicate the content in this database into the specified target database. Replication is restricted to the specified document ids. The target must exist.

Parameters:

target - database

docIds -

Returns:

ReplicationStatus

addToBulkBuffer

void addToBulkBuffer(java.lang.Object o)

Add the object to the bulk buffer attached to the executing thread. A subsequent call to either flushBulkBuffer or clearBulkBuffer is expected.

Parameters:

o -

flushBulkBuffer

java.util.List<DocumentOperationResult> flushBulkBuffer()

Sends the bulk buffer attached the the executing thread to the database (through a executeBulk call). The bulk buffer will be cleared when this method is finished.

clearBulkBuffer

void clearBulkBuffer()

Clears the bulk buffer attached the the executing thread.

executeBulk

java.util.List<DocumentOperationResult> executeBulk(java.util.Collection<?> objects)

Creates, updates or deletes all objects in the supplied collection. If the object has no revision set, it will be created, otherwise it will be updated. If the object's serialized json document contains a "_deleted"=true field it will be deleted. org.ektorp.BulkDeleteDocument.of(someObject) is the easiest way to create a delete doc for an instance. Some documents may successfully be saved and some may not. The response will tell the application which documents were saved or not. In the case of a power failure, when the database restarts some may have been saved and some not.

Parameters:

objects, - all objects will have their id and revision set.

Returns:

The list will only contain entries for documents that has any kind of error code returned from CouchDB. i.e. the list will be empty if everything was completed successfully.

executeAllOrNothing

java.util.List<DocumentOperationResult> executeAllOrNothing(java.util.Collection<?> objects)

Creates, updates or deletes all objects in the supplied collection. In the case of a power failure, when the database restarts either all the changes will have been saved or none of them. However, it does not do conflict checking, so the documents will be committed even if this creates conflicts.

Parameters:

objects, - all objects will have their id and revision set.

Returns:

The list will only contain entries for documents that has any kind of error code returned from CouchDB. i.e. the list will be empty if everything was completed successfully.

changes

java.util.List<DocumentChange> changes(ChangesCommand cmd)

Queries the database for changes. This is a one-off operation. To listen to changes continuously @see changesFeed(ChangesCommand cmd).

Parameters:

cmd -

Returns:

changesFeed

ChangesFeed changesFeed(ChangesCommand cmd)

Sets up a continuous changes feed. The current update sequence in the DB will be used if ChangesCommand does not specify the since parameter. A heartbeat interval of 10 seconds will be used if ChangesCommand does not specify the heartbeat parameter.

Parameters:

cmd -

Returns:

a running changes feed that buffers incoming changes in a unbounded queue (will grow until OutOfMemoryException if not polled).