Ektorp Reference Documentation

Here are some good reasons why you should consider to use Ektorp in your project:

Ektorp can be downloaded from https://github.com/helun/Ektorp/downloads

A sample application can be downloaded from the Ektorp site. It is a blog webapp aimed to showcase a basic Ektorp application. You can read more about it in the Ektorp tutorial.

Ektorp's standard implementation of the HttpClient interface is org.ektorp.http.StdHttpClient. It is created through a nested builder class: StdHttpClient.Builder

HttpClient authenticatedHttpClient = new StdHttpClient?.Builder()
                                .url("http://mychouchdbhost:5984")
                                .username("admin")
                                .password("secret")
                                .build();

StdHttpClient just wraps Apache HttpClient and exposes the following configuration properties:

If this is not enough for you, you can always create a org.apache.http.client.HttpClient yourself and pass it as a constructor argument to the StdHttpClient.

The standard implementation of the CouchDbInstance interface is org.ektorp.impl.StdCouchDbInstance. This interface provides methods for managing databases on the connected CouchDb instance.

StdCouchDbInstance provides two constructors:

The second constructor allows you to bring your own ObjectMapperFactory if you want full control on how Jackson is configured.

StdCouchDbInstance is thread-safe.

The standard implementation of the CouchDbConnector interface is org.ektorp.impl.StdCouchDbConnector. This interface provides methods for manipulating documents within a specific database.

StdCouchDbConnector provides two constructors:

The second constructor allows you to bring your own ObjectMapperFactory if you want full control on how Jackson is configured.

StdCouchDbConnector is thread-safe.

Here's a minimal example configuration that connects to a CouchDB instance on localhost:

import org.ektorp.*;
import org.ektorp.impl.*;
import org.ektorp.http.*;

...

HttpClient httpClient = new StdHttpClient.Builder().build()
CouchDbInstance dbInstance = new StdCouchDbInstance(httpClient);
// if the second parameter is true, the database will be created if it doesn't exists
CouchDbConnector db = dbInstance.createConnector("my_first_database", true);

// go!
...

Ektorp is mainly build for persisting rich domain classes in CouchDB much like classing ORM tools such as Hibernate. This is achieved by using the powerful object mapping features provided by the Jackson JSON library.

Your classes need to fulfill two requirements in order to be compatible with Ektorp:

Here's an example class:

import org.codehaus.jackson.annotate.*;

public class Sofa {

        
        private String id;
        private String revision;
        private String color;
        
        @JsonProperty("_id")
        public String getId() {
                return id;
        }

        @JsonProperty("_id")
        public void setId(String s) {
                id = s;
        }

        @JsonProperty("_rev")
        public String getRevision() {
                return revision;
        }

        @JsonProperty("_rev")
        public void setRevision(String s) {
                revision = s;
        }

        public void setColor(String s) {
                color = s;
        }
        
        public String getColor() {
                return color;
        }
}

...

@JsonProperty("_id")
public String getIdentifikator() {
    return identifikator;
}

...

...

@JsonProperty("_id")
private String id;

@JsonProperty("_rev")
private String rev;

...

import org.ektorp.support.CouchDbDocument;

public class Sofa extends CouchDbDocument{

        private String color;
        
        public void setColor(String s) {
                color = s;
        }
        
        public String getColor() {
                return color;
        }
}

package org.ektorp.sample;

import java.util.*;

import org.codehaus.jackson.annotate.*;
import org.ektorp.*;

public class Sofa extends CouchDbDocument {

        private String color;
        private int seats;
        private Date dateCreated;
        private List<String> imageURLs;
        private Map<String, Pillow> pillows;
        
        public void setColor(String s) {
                this.color = s;
        }
        
        public int getSeats() {
                return seats;
        }
        
        public void setSeats(int i) {
                this.seats = i;
        }
        
        public String getColor() {
                return color;
        }
        
        public List<String> getImageURLs() {
                return imageURLs;
        }
        
        public void setImageURLs(List<String> imageURLs) {
                this.imageURLs = imageURLs;
        }
        
        @JsonIgnore
        public int getNumberOfImages() {
                return imageURLs != null ? imageURLs.size() : 0;
        }
        
        public Map<String, Pillow> getPillows() {
                return pillows;
        }
        
        public void setPillows(Map<String, Pillow> pillows) {
                this.pillows = pillows;
        }
        
        @JsonProperty("date_created")
        public Date getDateCreated() {
                return dateCreated;
        }
        
        @JsonProperty("date_created")
        public void setDateCreated(Date dateCreated) {
                this.dateCreated = dateCreated;
        }
}

package org.ektorp.sample;

import org.codehaus.jackson.annotate.*;

public class Pillow {
        
        public enum Softness {SOFT, MEDIUM, FIRM}
        
        private final Softness softness;
        
        @JsonCreator
        public Pillow(@JsonProperty("softness") Softness s) {
            softness = s;
        }
        
        public Softness getSoftness() {
            return softness;
        }
}

public class BlogPost {

    @JsonProperty("_id")
    private String id;

    @JsonProperty("_rev")
    private String rev;

    @DocumentReferences(backReference = "blogPostId", fetch = FetchType.LAZY, descendingSortOrder = true, orderBy = "dateCreated")
    private Set<Comment> comments;

...

ObjectMapper myMapper = new ObjectMapper();

myMapper.getSerializationConfig().addMixInAnnotations(Target.class, MixIn.class);
myMapper.getDeserializationConfig().addMixInAnnotations(Target.class, MixIn.class);


CouchDbConnector db = new StdCouchDbConnector("myDBName", dbInstance, myMapper);

@JsonSerialize(include = Inclusion.NON_NULL)
abstract class MixIn

  @JsonProperty("_id") abstract int getFoo(); // rename property
  @JsonProperty("_rev") abstract int getBar(); // rename property
  @JsonIgnore int getSize(); // we don't need it!
  
}

@JsonSerailize(using = MySpecialType.Serializer.class)
public class MySpecialDocument {

    String id;
    String revision;
    
    ... rest of class goes here ...
    
    public static class Serializer extends JsonSerializer<MySpecialType> {

        @Override
        public void serialize(MySpecialType value, JsonGenerator jgen,
                SerializerProvider provider) throws IOException,
                JsonProcessingException {
            jgen.writeStartObject();
            jgen.writeStringField("_id", value.id);
            jgen.writeStringField("_rev", value.revision);
            ...
            etc etc
            ...
            jgen.writeEndObject();
        }
        
    }
}

import org.ektorp.util.DocumentAccessor;
import org.ektorp.util.Documents;

class MyDocumentAccessor implements DocumentAccessor {
    /**
    * @return true if document type's id field can be mutated.
    */
    public boolean hasIdMutator() {
        return true;
    }

    public String getId(Object o) {
        return cast(o).foo;
    }

    public void setId(Object o, String id) {
        cast(o).foo = rev;
    }

    public String getRevision(Object o) {
        return cast(o).bar;
    }

    public void setRevision(Object o, String rev) {
        cast(o).bar = rev;
    }

    private MyType cast(Object o) {
        return (MyType) o;
    }

}

Documents.registerAccessor(MyType.class, new MyDocumentAccessor());

// here's a Junit snippet you can use to test your accessor:
MyType myType = new MyType();
Documents.setId(myType, "my_id");
assertEquals("my_id", Documents.getId(myType));
assertTrue(Documents.isNew(myType));

It is possible to read and write documents mapped as java.util.Map<String, Object>. This is convenient if you have documents that have a simple structure and a small number of fields.

    
    List<String> countries = ...
    Map<String, List<String>> majorCitiesByCountry = ...
    
    Map<String, Object> referenceData = new HashMap<String, Object>();
    referenceData.put("_id", "referenceData");
    referenceData.put("countries", countries);
    referenceData.put("majorCitiesByCountry", majorCitiesByCountry);
    
    db.create(referenceData);

    Map<String, Object> referenceData_2 = db.get(Map.class, "referenceData")
    ...

If you like to work with your documents in a DOM-style manner your can use org.codehaus.jackson.JsonNode. This is useful if you want to modify documents without creating explicit Java types for them. JsonNode is more powerful than java.util.Map when it comes to traversing and modifying the document.

import org.ektorp.*;
import org.codehaus.jackson.*;
import org.codehaus.jackson.node.*;

    ...

    JsonNode doc = db.get(JsonNode.class, "myDoc");
        
    JsonNode address = doc.findPath("address");
    if (address.isObject()) {
        ObjectNode a = (ObjectNode) address;
        a.put("city", "Stockholm");
    }
        
    db.update(doc);

Sofa sofa = ...

CouchDbConnector db = ...
db.create(sofa);

// both id and revision will be set after create
String id = sofa.getId();
String revision = sofa.getRevision();

If the object being created does not have an id set, CouchDB will generate one. Both id and revision will be set after the create operation.

Get the latest revision of a document from the database:

String id = ...
Sofa sofa = db.get(Sofa.class, id);

If the desired document does not exists in the database an org.ektorp.DocumentNotFoundException is thrown.

If you need to fetch a specific revision:

String id = ...
String rev = ...
Sofa sofa = db.get(Sofa.class, id, rev);

Read a document as a raw stream:

String id = ...
InputStream doc = db.getAsStream(id);

InputStream olderRev = db.getAsStream(id, rev);

String id = ...
String rev = ...
Options options = new Options().revision(rev);
Sofa sofa = db.get(Sofa.class, id, options);

String id = ...
Options options = new Options().includeConflicts();
Sofa sofa = db.get(Sofa.class, id, options);

String id = ...
Options options = new Options().includeRevisions();
Sofa sofa = db.get(Sofa.class, id, options);

String id = ...
Options options = new Options().param("paramName","paramValue");
Sofa sofa = db.get(Sofa.class, id, options);

Sofa sofa = ...
db.update(sofa)
// revision will be updated after update
sofa.getRevision();

If the there exists a newer revision of the document in the database, an org.ektorp.UpdateConflictException is thrown.

Note that calling update with an object that has an empty id field will create a new document in the database.

                File file = someMethodToGetFile();
                InputStream jsonInputStream = new FileInputStream(file);
                db.update("document_id",
                          jsonInputStream,
                          file.length(),
                          null);
            

Both the id and revision of an object is required in order to delete it:

String id = ...
String revision = ...
db.delete(id, revision):

If the there exists a newer revision of the document in the database, an org.ektorp.UpdateConflictException is thrown.

As a convenience, a whole object can also be passed as an argument:

Sofa sofa = ...
db.delete(sofa)

// the map contains revisions by doc id to purge
Map<String,List<String>> revisionsToPurge = ...
PurgeResult result = db.purge(revisionsToPurge);

Ektorp provides full support for the bulk document operations available in CouchDB.

List<String> docIds = ...

ViewQuery q = new ViewQuery()
                      .allDocs()
                      .includeDocs(true)
                      .keys(docIds);

List<Sofa> bulkLoaded = db.queryView(q, Sofa.class);

List<DocumentOperationResult> executeBulk(Collection<?> objects);

List<DocumentOperationResult> executeAllOrNothing(Collection<?> objects);

List<Object> bulkDocs = ...
Sofa toBeDeleted = ...
        
bulkDocs.add(BulkDeleteDocument.of(toBeDeleted));
        
db.executeBulk(bulkDocs);

Here is a minimal repository based on org.ektorp.support.CouchDbRepositorySupport:

package org.ektorp.sample;

import java.util.*;
import org.ektorp.*;

public class SofaRepository extends CouchDbRepositorySupport<Sofa> {

        public SofaRepository(CouchDbConnector db) {
                super(Sofa.class, db);
        }

        public List<Sofa> findByColor(String color) {
                return queryView("by_color", color);
        }
}

This repository above doesn't look like much but CouchDbRepositorySupport has provided the following methods to the SofaRepository:

public void add(Sofa entity);
public void update(Sofa entity);
public void remove(Sofa entity);
public Sofa get(String id);
public Sofa get(String id, String rev);
public List<T> getAll();
public boolean contains(String docId);

When using support methods like queryView the underlying code assumes that the database contains a design document with an id adhering to the naming convention:

_design/[repository type simple name]

e.g. the repository in the previous section expects that the document _design/Sofa exists in the database.

Calling queryView without the standard design document defined will cause an exception to be thrown.

[{"_id":"_design/Sofa",
    "views":{
        "all": {"map": "function(doc) { if (doc.type = 'Sofa' ) emit( null, doc._id ) } "}
     }
}]

Repositories based on CouchDbRepositorySupport may define the views used by the repository through annotations in the repository class.

@View( name = "all", map = "function(doc) { if (doc.type == 'Sofa' ) emit( null, doc._id )}")
public class SofaRepository extends CouchDbRepositorySupport<Sofa> {

    @View( name = "avg_sofa_size", map = "function(doc) {...}", reduce = "function(doc) {...}")
    public int getAverageSofaSize() {
        ViewResult r = db.queryView(createQuery("avg_sofa_size"));
        return r.getRows().get(0).getValueAsInt();
    }

}

If you have many view definition you can group them with the @Views annotation:

@Views({
    @View(name = "view_1", map = "function(doc) { ... }"),
    @View(name = "view_2", map = "function(doc) { ... }"),
    @View(name = "view_3", map = "function(doc) { ... }")
    })
public class MyRepository {
    ...

@View and @Views and can be defined at class level or at method level.

View creation is triggered by calling the method: initStandardDesignDocument in CouchDbRepositorySupport.

If the standard design document doesn't exists, it will be created.

function(doc)
{
    much javascript here
}

@View( name = "complicated_view", map = "classpath:myMapFunction.js")
public int getAverageSofaSize() {
    ViewResult r = db.queryView(createQuery("complicated_view.json"));
    return r.getRows().get(0).getValueAsInt();
}

CouchDbRepositorySupport is able to generate some views automatically. Simple finder methods can be annotated with the @GenererateView annotation.

...
@GenerateView
public List<Sofa> findByColor(String color) {
    return queryView("by_color", color);
}
...

In order for @GenerateView to work properly, the following requirements has to be fulfilled:

The generated view will be named by_[property].

View generation is triggered by calling the method: initStandardDesignDocument in CouchDbRepositorySupport.

If the standard design document doesn't exists, it will be created.

public class BlogPost {

    @JsonProperty("_id")
    private String id;

    @JsonProperty("_rev")
    private String rev;

    // this field marks blog post documents in the db 
    @TypeDiscriminator
    private String title;

...

// the declared string is inserted as a part of if statements int the generated view's map function.
@TypeDiscriminator("doc.title && doc.myField === 'special_value'")
public class BlogPost {

    @JsonProperty("_id")
    private String id;

    @JsonProperty("_rev")
    private String rev

    private String title;

    private String myField;

...

Repositories based on CouchDbRepositorySupport may also define list, show and filter functions through annotations in the repository class.

They all have the same functionality, it is just the type of function that differs:

@Filter( name = "my_filter" file = "my_filter.js")
@ListFunction( name = "my_list_function" file = "my_list_function.js")
@ShowFunction( name = "my_show_function" file = "my_show_function.js")
@UpdateHandler( name = "my_show_function" file = "my_update_handler.js")
public class MyRepository {
    ...

Multiple functions can be grouped with the corresponding annotations @Filters, @Lists, @Shows and @UpdateHandlers.

These annotations behaves in effect as the @View and @Views annotations described in section 3 of this chapter.

Attachments can be stored along with its parent document by embedding them in the parent document. The attachment itself has to be Base64 encoded in this case as the whole document including the attachment will be serialized into a string.

Note that the Sofa class in the example below extends CouchDbDocument and exposes the protected method addInlineAttachment(Attachment a).

String base64EncodedData = ...
Sofa sofa = ...

Attachment inline = new Attachment("attachment_id", base64EncodedData, "image/jpeg");

sofa.addInlineAttachment(inline);
db.update(sofa);

An attachment and its parent document can be created in the same operation. This is useful if you just want to store the data "as is" and don't really use the actual document, i.e. when storing an image.

InputStream data = ...
String contentType = "image/jpeg";

AttachmentInputStream a = new AttachmentInputStream("attachment_id",
                                                     data,
                                                     contentType);

db.createAttachment("new_document_id", a);

If you don't want to add the attachment in-line, you can add attachments in an separate operation.

AttachmentInputStream a = new AttachmentInputStream("attachment_id",
                                                     data,
                                                     contentType);

db.createAttachment("existing_document_id", "document_revision", a);

To retrieve the attachment's content:

AttachmentInputStream data = db.getAttachment("document_id",
                                              "attachment_id");

The entity base class org.ektorp.support.CouchDbDocument provides an accessor for the document's attachments. The list contains stub attachments.

Couch supports updating a document along with attachments as a MIME multipart/related message. This is an efficient way to update a document along with attachments since it does not require Base64 encoding.

To update a document as a MIME multipart/related in Ektorp, use the updateMultipart() method of CouchDbConnector.

              File file = someMethodToGetFile();
              InputStream mimeInputStream = new FileInputStream(file);
              db.updateMultipart("document_id",
                                 mimeInputStream,
                                 "abc_boundary",
                                 file.length(),
                                 new Options());
          

The data in the InputStream must contain only the MIME multipart/related message. This message is specifed in CouchDB Multiple Attachments API .

Objects can be loaded directly from view results as long as the result contain documents. The document can either be included in the view result by specifying the query parameter includeDocs(true) or be emitted directly by the view into the value field.

ViewQuery query = new ViewQuery()
                     .designDocId("_design/Sofa")
                     .viewName("by_color")
                     .key("red");
                
List<Sofa> redSofas = db.queryView(query, Sofa.class);

It is possible to query for scalar values.

ViewQuery query = new ViewQuery()
          .designDocId("_design/somedoc")
          .viewName("some_view_name");
                
ViewResult result = db.queryView(query);
for (ViewResult.Row row : result.getRows()) {
    String stringValue = row.getValue();
    int intValue = row.getValueAsInt();
}

The key, value and doc fields can be access as a org.jackson.JsonNode:

ViewResult result = db.queryView(query);
for (ViewResult.Row row : result) {
    JsonNode keyNode = row.getKeyAsNode();
    JsonNode valueNode = row.getValueAsNode();
    JsonNode docNode = row.getDocAsNode();
    ...
}

The most flexible method is query for stream. The result is returned as a stream. It is important that the stream is closed after usage as resource leaks otherwise will occur.

ViewQuery query = new ViewQuery()
                       .designDocId("_design/somedoc")
                       .viewName("view_with_huge_result");

InputStream data = db.queryForStream(query);
...
data.close();

If your views produce complex keys such as [2010, 6, 1], you should construct your key through the class org.ektorp.ComplexKey

ComplexKey start = ComplexKey.of(2010, 6, 1);
ComplexKey end = ComplexKey.of(2010, 10, 1);
        
ViewQuery query = new ViewQuery()
                       .designDocId("_design/Order")
                       .viewName("by_orderDate")
                       .startKey(start)
                       .endKey(end);

If you want to use a wild card in your key, often used in date ranges, add a ComplexKey.emptyObject():

    // will render to [2010, {}]
    ComplexKey allOf2010 = ComplexKey.of(2010, ComplexKey.emptyObject());

CouchDbConnector provides a method for querying views for paged results. The implementation is based on the recipe described in the book "CouchDB The Definitive Guide"

Querying a view for a page starts with the querying for the first page:

// create a page request with a page size of 5 
PageRequest pageRequest = PageRequest.firstPage(5);

ViewQuery query = new ViewQuery()
                       .designDocId("_design/Order")
                       .viewName("by_orderDate")
                       .includeDocs(true);

Page<Order> result = db.queryForPage(query, pageRequest, Order.class);

// Page is iterable
for (Order o : result) {
    // do something here
}

Requesting the next page is a simple affair:

Page<Order> previousPage = ...
PageRequest nextPageRequest = previousPage.getNextPageRequest();

Page<Order> nextPage = db.queryForPage(query, nextPageRequest, Order.class);

// requesting the previous page:
PageRequest prevPageRequest = nextPage.getPreviousPageRequest();

<c:if test="${page.hasPrevious}">
    <a href="/blog/posts/?p=${page.previousLink}">Previous page</a>
</c:if>

@RequestMapping( value = "/posts/", method = RequestMethod.GET)
public String viewAll(Model m, @RequestParam(value = "p", required = false) String pageLink) {
    PageRequest pr = pageLink != null ? PageRequest.fromLink(pageLink) : PageRequest.firstPage(5);
    m.addAttribute(blogPostRepo.getAll(pr));
    return "/posts/index";
}

If you enable the cache in a query, the result may be stale depending on how your view is constructed.

The cache works through conditional gets that invalidates the cache if the view's etag has changed. It is possible that an document update don't cause the view contents to be updated and hence the cache will not be invalidated. If you emit a timestamp or the document's revision as the view value the cache will be properly invalidated.

Ektorp provides a continuous changes feed through the class org.ektorp.changes.ChangesFeed. The ChangesFeed provides an API that is similar to a BlockingQueue:

ChangesCommand cmd = new ChangesCommand.Builder().build();

ChangesFeed feed = db.changesFeed(cmd);

while (feed.isAlive()) {
    DocumentChange change = feed.next();
    String docId = change.getId();
    ...
}

If you don't want to wait indefinitely for changes the ChangesFeed class provides a variant if the feed method where a time out can be specified.

If continuous notifications are not needed, the database can be queried through the changes method in CouchDbConnector:

int dbSequenceNumber = ... // is available in the class org.ektorp.DbInfo obtained through db.getDbInfo();

ChangesCommand cmd = new ChangesCommand.Builder()
                         .since(dbSequenceNumber)
                         .build();

List<DocumentChange> changes = db.changes(cmd);
for(DocumentChange change : changes) {
    ...
}

Database replication can be initiated through in two ways:

CouchDbInstance dbInstance = ...

ReplicationCommand cmd = new ReplicationCommand.Builder()
                                 .source("example-database")
                                 .target("http://example.org/example-database")
                                 .build();

ReplicationStatus status = dbInstance.replicate(cmd);

CouchDbConnector db = ...

ReplicationStatus status = db.replicateFrom("example-database");

// or

ReplicationStatus status2 = db.replicateTo("http://example.org/example-database");

Ektorp Spring module comes with a Spring XML namespace that simplifies the Ektorp configuration in an application context.

The following xml-snippet will create an CouchDbConnector connected to the database named "myDatabase". If an id is not declared the connector will be registered with the same id as the database name in the application context:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:couchdb="http://www.ektorp.org/schema/couchdb"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.ektorp.org/schema/couchdb http://www.ektorp.org/schema/couchdb/couchdb.xsd">

    <couchdb:database name="myDatabase" url="http://localhost:5984"/>

</beans>

If you need multiple connectors connected to the same CouchDB instance, the CouchDbInstance bean can be explicitly declared:

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:couchdb="http://www.ektorp.org/schema/couchdb"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.ektorp.org/schema/couchdb http://www.ektorp.org/schema/couchdb/couchdb.xsd">

    <couchdb:instance id="localCouchDB" url="http://localhost:5984/" />

    <couchdb:database name="myDatabase" instance-ref="localCouchDB" />

    <couchdb:database name="myOtherDatabase" instance-ref="localCouchDB" />

</beans>

If you need to specify more properties to Ektorp you can just refer to them when the CouchDB instance is declared:

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:couchdb="http://www.ektorp.org/schema/couchdb"
    xmlns:util="http://www.springframework.org/schema/util"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.ektorp.org/schema/couchdb http://www.ektorp.org/schema/couchdb/couchdb.xsd
        http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.xsd">

    <util:properties id="couchdbProperties" location="classpath:/couchdb.properties"/>

    <couchdb:instance id="localCouchDB" url="http://localhost:5984" properties="couchdbProperties" />

    <couchdb:database name="myDatabase" instance-ref="localCouchDB" />

</beans>

If you for some reason cannot use the XML namespace described in the previous section, you can use the class org.ektorp.spring.HttpClientFactoryBean to configure a HttpClient in the application context.

When added to the appllication context, the factory will read configuration from couchdbProperties defined in the application context:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:util="http://www.springframework.org/schema/util"
    xmlns:context="http://www.springframework.org/schema/context"
    xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-3.0.xsd
        http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">

    <util:properties id="couchdbProperties" location="classpath:/couchdb.properties"/>

    <bean id="httpClient" class="org.ektorp.spring.HttpClientFactoryBean" />

    <bean id="couchDbInstance" class="org.ektorp.impl.StdCouchDbInstance">
        <constructor-arg ref="httpClient"/>
    </bean>

    <bean id="initialDataLoader" class="org.ektorp.spring.InitialDataLoader" autowire="byType" init-method="loadData"/>

</beans>

And here is a couchdb.properties to cut & paste:

host=localhost
port=5984
maxConnections=20
connectionTimeout=1000
socketTimeout=10000
username=CouchDB_Admin
password=geheimnis

The Ektorp Spring module features a class for loading the database with documents at application startup.

The org.ektorp.spring.InitialDataLoader will lookup all beans in the application context that implements org.ektorp.dataload.DataLoader (typically your repositories) and feed them data streams loaded from locations specified by the DataLoaders themselves.

<bean class="org.ektorp.spring.InitialDataLoader" autowire="constructor"/>

<context:component-scan base-package="org.example">
    <context:include-filter type="regex" expression="org\.ektorp\.spring.*"/>
</context:component-scan>

import org.ektorp.dataload.*;
import org.ektorp.support.*;

class SofaRepository extends CouchDbRepositorySupport<Sofa> implements DataLoader {

    private final static String[] INITIAL_DATA_PATH = {"classpath:/init_sofa_data.json"};

    public void loadInitialData(Reader in) {
        new DefaultDataLoader(db).load(in);
    }
  
    public String[] getDataLocations() {
        return INITIAL_DATA_PATH;
    }

    /**
    * Is called when all DataLoaders in the system has loaded it´s data.
    */
    public void allDataLoaded() {

    }
}

Ektorp has a custom implementation of the HttpClient interface for Android org.ektorp.android.http.AndroidHttpClient. It is designed to use the version of Apache HttpClient included in the Android platform: AnddroidHttpClient.Builder

HttpClient authenticatedHttpClient = new AndroidHttpClient.Builder()
                                .url("http://mychouchdbhost:5984")
                                .username("admin")
                                .password("secret")
                                .build();

When using AndroidHttpClient you should NOT include the httpclient or httpcore libraries in your project. Android includes a copy of Apache HttpClient and supplying your own copy can lead to difficult to debug class loading exceptions.

NOTE: AndroidHttpClient does not support caching.

The EktorpAsyncTask class extends the Android platform's AsyncTask class to perform Ektorp operations on a background thread, while handling success and failure conditions on the application's main thread. This is important since performing network operations on the main thread may lead to NetworkOnMainThreadException. Further, you can only interact with the Android UI from the main thread.

The ChangesFeedAsyncTask is another class extending the Android platform's AsyncTask class. This class allows you to follow a CouchDB changes feed in a background thread and receive the DocumentChange objects on the main thread.

public class ExampleChangesFeedAsyncTask extends ChangesFeedAsyncTask {

    private Context context;

    public ExampleChangesFeedAsyncTask(Context context, CouchDbConnector couchDbConnector, ChangesCommand changesCommand) {
        super(couchDbConnector, changesCommand);
        this.context = context;
    }

    @Override
    protected void handleDocumentChange(DocumentChange change) {
        Toast.makeText(context, "Received change sequence : " + change.getSequence(), 5000).show();
    }

    @Override
    protected void onDbAccessException(DbAccessException dbAccessException) {
        Log.e(TAG, "DbAccessException following changes feed", dbAccessException);
    }

}

Then to use this class:

ChangesCommand changesCmd = new ChangesCommand.Builder().since(lastUpdate).continuous(true).build();
ExampleChangesFeedAsyncTask couchChangesAsyncTask = new ExampleChangesFeedAsyncTask(couchDbConnector, changesCmd);
couchChangesAsyncTask.execute();
    

The CouchbaseViewListAdapter class extends the Android platform's BaseAdapter class. This class allows you populate the rows of an Android ListView. with content from the rows of a CouchDB view. Optionally, you can have it follow the changes feed and update the list when the data changes.

public class ExampleListAdapter extends CouchbaseViewListAdapter {

    private Context context;

    public ExampleListAdapter(Context context, CouchDbConnector couchDbConnector, ViewQuery viewQuery, boolean followChanges) {
        super(couchDbConnector, viewQuery, followChanges);
        this.context = context;
    }

    @Override
    public View getView(int position, View itemView, ViewGroup parent) {
        if (itemView == null) {
            LayoutInflater li = (LayoutInflater)context.getSystemService(Context.LAYOUT_INFLATER_SERVICE);
            itemView = li.inflate(R.layout.grocery_list_item, null);
        }

        TextView label = (TextView) itemView.findViewById(R.id.label);
        Row row = getRow(position);
        JsonNode item = row.getValueAsNode();
        JsonNode itemText = item.get("text");
        if(itemText != null) {
            label.setText(itemText.getTextValue());
        }

        return itemView;
    }
}
    

To use this adapter:

ViewQuery viewQuery = new ViewQuery().designDocId(dDocId).viewName(viewName);
ExampleListAdapter itemListViewAdapter = new ExampleListAdapter(this, couchDbConnector, viewQuery, true);
listView.setAdapter(itemListViewAdapter);