org.ektorp

Interface CouchDbConnector

All Superinterfaces:

LocalBulkBuffer

All Known Implementing Classes:

StdCouchDbConnector, StreamedCouchDbConnector

public interface CouchDbConnector
extends LocalBulkBuffer

Primary interface for working with Objects mapped as documents in CouchDb. The Id and revision of mapped Objects must be accessible by org.ektorp.util.Documents class.

Author:

henrik lundgren

Method Summary

Methods

Modifier and Type	Method and Description
String	callUpdateHandler(String designDocID, String function, String docId)
String	callUpdateHandler(String designDocID, String function, String docId, Map<String,String> params)
String	callUpdateHandler(UpdateHandlerRequest req)
<T> T	callUpdateHandler(UpdateHandlerRequest req, Class<T> c)
List<DocumentChange>	changes(ChangesCommand cmd) Queries the database for changes.
StreamingChangesResult	changesAsStream(ChangesCommand cmd) Queries the database for changes. this operation gives you the result as a iterable stream of documentchange objects, the stream should be closed when finished
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	compact() Compaction compresses the database file by removing unused sections created during updates.
void	compactViews(String designDocumentId) This compacts the view index from the current version of the design document.
boolean	contains(String id) Check if the database contains a document.
String	copy(String sourceDocId, String targetDocId) Copies a document to the target document id.
String	copy(String sourceDocId, String targetDocId, String targetRevision) Copies a document and overwrites the target document.
void	create(Object o) Creates the Object as a document in the database.
void	create(String id, Object o)
String	createAttachment(String docId, AttachmentInputStream data) Creates both the document and the attachment
String	createAttachment(String docId, 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.
String	delete(Object o) Deletes the Object in the database.
String	delete(String id, String revision) Deletes the document in the database.
String	deleteAttachment(String docId, String revision, String attachmentId)
void	ensureFullCommit() Commits any recent changes to the specified database to disk.
List<DocumentOperationResult>	executeAllOrNothing(Collection<?> objects) Creates, updates or deletes all objects in the supplied collection.
List<DocumentOperationResult>	executeAllOrNothing(InputStream inputStream) Creates, updates or deletes all objects in the supplied collection.
List<DocumentOperationResult>	executeBulk(Collection<?> objects) Creates, updates or deletes all objects in the supplied collection.
List<DocumentOperationResult>	executeBulk(InputStream inputStream) Creates, updates or deletes all objects in the supplied collection.
<T> T	find(Class<T> c, String id) Same as get(Class c, String id) with the difference that null is return if the document was not found.
<T> T	find(Class<T> c, String id, Options options) Same as get(Class c, String id, Options options) with the difference that null is return if the document was not found.
<T> T	get(Class<T> c, String id)
<T> T	get(Class<T> c, String id, Options options)
<T> T	get(Class<T> c, String id, String rev) Deprecated. use get(Class c, String id, Options options)
List<String>	getAllDocIds()
InputStream	getAsStream(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.
InputStream	getAsStream(String id, Options options) 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.
InputStream	getAsStream(String id, String rev) Deprecated. use getAsStream(String id, Options options)
AttachmentInputStream	getAttachment(String id, String attachmentId) Reads an attachment from the database.
AttachmentInputStream	getAttachment(String id, String attachmentId, String revision)
HttpClient	getConnection() Convenience method for accessing the underlying HttpClient.
String	getCurrentRevision(String id) Obtain the current revision of a document using a lightweight request.
String	getDatabaseName()
DbInfo	getDbInfo() Provides meta information about this database.
DesignDocInfo	getDesignDocInfo(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
List<Revision>	getRevisions(String id)
<T> T	getWithConflicts(Class<T> c, String id) Deprecated. use get(Class c, String id, Options options)
String	path()
PurgeResult	purge(Map<String,List<String>> revisionsToPurge) Permanently removes the references to deleted documents from the database.
<T> Page<T>	queryForPage(ViewQuery query, PageRequest pr, Class<T> type) Provides paged view results.
InputStream	queryForStream(ViewQuery query)
StreamingViewResult	queryForStreamingView(ViewQuery query) Please note that the StreamingViewResult need to be closed after usage.
ViewResult	queryView(ViewQuery query)
<T> List<T>	queryView(ViewQuery query, 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(String source) Replicate the content in the source database into this database.
ReplicationStatus	replicateFrom(String source, Collection<String> docIds) Replicate the content in the source database into this database.
ReplicationStatus	replicateTo(String target) Replicate the content in this database into the specified target database.
ReplicationStatus	replicateTo(String target, Collection<String> docIds) Replicate the content in this database into the specified target database.
void	setRevisionLimit(int limit)
void	update(Object o) Updates the document.
void	update(String id, InputStream document, long length, Options options) Sends a document to the Couch server as a JSON stream
void	updateMultipart(String id, InputStream stream, String boundary, long length, Options options) Sends a document to the Couch server as a MIME multipart/related message.

Methods inherited from interface org.ektorp.LocalBulkBuffer

addToBulkBuffer, clearBulkBuffer, flushBulkBuffer

Method Detail

create

void create(String id,
          Object o)

Parameters:

id -

the - object to store in the database

Throws:

UpdateConflictException - if there was an update conflict.

create

void create(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(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

String delete(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

String delete(String id,
            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.

copy

String copy(String sourceDocId,
          String targetDocId)

Copies a document to the target document id. Useful when you want to duplicate docs with large attachments.

Parameters:

sourceDocId -

targetDocId -

Returns:

revision of the target document.

copy

String copy(String sourceDocId,
          String targetDocId,
          String targetRevision)

Copies a document and overwrites the target document. Useful when you want to duplicate docs with large attachments.

Parameters:

sourceDocId -

targetDocId -

targetRevision -

Returns:

revision of the target document.

purge

PurgeResult purge(Map<String,List<String>> revisionsToPurge)

Permanently removes the references to deleted documents from the database.

Parameters:

revisionsToPurge - document IDs & revisions to be purged

Returns:

contains the purge sequence number, and a list of the document IDs and revisions successfully purged.

get

<T> T get(Class<T> c,
        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(Class<T> c,
        String id,
        Options options)

Parameters:

c - the target class to map to.

id - the id of the document in the database.

options -

Returns:

the document mapped as the specified class.

Throws:

DocumentNotFoundException - if the document was not found.

find

<T> T find(Class<T> c,
         String id)

Same as get(Class c, String id) with the difference that null is return if the document was not found.

Parameters:

c -

id -

Returns:

null if the document was not found.

find

<T> T find(Class<T> c,
         String id,
         Options options)

Same as get(Class c, String id, Options options) with the difference that null is return if the document was not found.

Parameters:

c -

id -

options -

Returns:

null if the document was not found.

get

@Deprecated
<T> T get(Class<T> c,
                   String id,
                   String rev)

Deprecated. use get(Class c, String id, Options options)

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

@Deprecated
<T> T getWithConflicts(Class<T> c,
                                String id)

Deprecated. use get(Class c, String id, Options options)

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(String id)

Check if the database contains a document.

Parameters:

id -

Returns:

true if a document with the id exists in the database

getAsStream

InputStream getAsStream(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

@Deprecated
InputStream getAsStream(String id,
                                 String rev)

Deprecated. use getAsStream(String id, Options options)

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.

getAsStream

InputStream getAsStream(String id,
                      Options options)

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 -

options -

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

List<Revision> getRevisions(String id)

Parameters:

id -

Returns:

Throws:

DocumentNotFoundException - if the document was not found.

getCurrentRevision

String getCurrentRevision(String id)

Obtain the current revision of a document using a lightweight request.

Parameters:

id -

Returns:

Throws:

DocumentNotFoundException - if the document was not found.

getAttachment

AttachmentInputStream getAttachment(String id,
                                  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.

getAttachment

AttachmentInputStream getAttachment(String id,
                                  String attachmentId,
                                  String revision)

createAttachment

String createAttachment(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

String createAttachment(String docId,
                      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

String deleteAttachment(String docId,
                      String revision,
                      String attachmentId)

Parameters:

docId -

revision -

attachmentId -

Returns:

the new revision of the document

Throws:

UpdateConflictException - if there was an update conflict.

getAllDocIds

List<String> getAllDocIds()

Returns:

all document ids in the database including design document ids.

queryView

<T> List<T> queryView(ViewQuery query,
                    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.

queryForPage

<T> Page<T> queryForPage(ViewQuery query,
                       PageRequest pr,
                       Class<T> type)

Provides paged view results. Implementation based on the recipe described in the book "CouchDB The Definitive Guide" http://guide.couchdb.org/editions/1/en/recipes.html#pagination This method has the same requirements for the view as the method queryView(ViewQuery query, Class type).

Parameters:

query -

pr -

type -

Returns:

queryView

ViewResult queryView(ViewQuery query)

Parameters:

query -

Returns:

queryForStreamingView

StreamingViewResult queryForStreamingView(ViewQuery query)

Please note that the StreamingViewResult need to be closed after usage.

Parameters:

query -

Returns:

the view result as a iterable stream.

queryForStream

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

String getDatabaseName()

Returns:

name

path

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(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(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(String source)

Replicate the content in the source database into this database.

Parameters:

source - database

Returns:

ReplicationStatus

replicateFrom

ReplicationStatus replicateFrom(String source,
                              Collection<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(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(String target,
                            Collection<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

executeBulk

List<DocumentOperationResult> executeBulk(InputStream inputStream)

Creates, updates or deletes all objects in the supplied collection. If the json has no revision set, it will be created, otherwise it will be updated. If the json document contains a "_deleted"=true field it will be deleted. 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:

an - json array with documents ex [{"_id":"1", "name": "hello world" }, "_id":"2", "name": "hello world 2"}]

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

List<DocumentOperationResult> executeAllOrNothing(InputStream inputStream)

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:

an - json array with documents

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.

executeBulk

List<DocumentOperationResult> executeBulk(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

List<DocumentOperationResult> executeAllOrNothing(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

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:

changesAsStream

StreamingChangesResult changesAsStream(ChangesCommand cmd)

Queries the database for changes. this operation gives you the result as a iterable stream of documentchange objects, the stream should be closed when finished

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

callUpdateHandler

String callUpdateHandler(String designDocID,
                       String function,
                       String docId)

Parameters:

designDoc -

function -

docId -

Returns:

callUpdateHandler

String callUpdateHandler(String designDocID,
                       String function,
                       String docId,
                       Map<String,String> params)

Parameters:

designDoc -

function -

docId -

params -

Returns:

callUpdateHandler

<T> T callUpdateHandler(UpdateHandlerRequest req,
                      Class<T> c)

callUpdateHandler

String callUpdateHandler(UpdateHandlerRequest req)

ensureFullCommit

void ensureFullCommit()

Commits any recent changes to the specified database to disk.

updateMultipart

void updateMultipart(String id,
                   InputStream stream,
                   String boundary,
                   long length,
                   Options options)

Sends a document to the Couch server as a MIME multipart/related message.

Parameters:

id - the document ID

stream - an InputStream of the multipart message containing the document and any attachments

boundary - the boundary of the multipart/related message parts

length - the length of the MIME multipart message stream

options - options to pass to the Couch request

update

void update(String id,
          InputStream document,
          long length,
          Options options)

Sends a document to the Couch server as a JSON stream

Parameters:

id - the document ID

document - an InputStream of the JSON document

length - the length of the JSON document

options - options to pass to the Couch request