Ektorp is a persistence API that uses [http://couchdb.apache.org/ CouchDB] as storage engine. The goal of Ektorp is to combine JPA like functionality with the simplicity and flexibility that CouchDB provides.

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

• Rich domain models. With powerful JSON-object mapping provided by Jackson it is easy to create rich domain models.
• Schemaless comfort. As CouchDB is schemaless, the database gets out of the way during application development. With a schemaless database, most adjustments to the database become transparent and automatic.
• Out-of-the-Box CRUD. The generic repository support makes it trivial to create persistence classes.
• Simple and fluent API.
• Spring Support. Ektorp features an optional spring support module.
• Active development. Ektorp is actively developed and has a growing community.
• Choice of abstraction level. From full object-document mapping to raw streams, Ektorp will never stop you if you need to step down an abstraction level.

• Ektorp 1.1.1 released! [http://code.google.com/p/ektorp/downloads/detail?name=ektorp-1.1.1-all.zip Download] | [http://code.google.com/p/ektorp/wiki/Changelog Changelog]
• New [http://www.ektorp.org/reference_documentation.html reference documentation] is available.
• A simple Ektorp sample application is now available [http://ektorp.org/tutorial.html here]
• Ektorp is available in the central Maven repository. [http://www.ektorp.org/reference_documentation.html#d99e68 Artifact info]

It is very easy to get started with Ektorp:

HttpClient httpClient = new StdHttpClient.Builder()
                                .host("localhost")
                                .port(5984)
                                .build();

CouchDbInstance dbInstance = new StdCouchDbInstance(httpClient);
CouchDbConnector db = new StdCouchDbConnector("mydatabase", dbInstance);

db.createDatabaseIfNotExists();

Sofa sofa = db.get(Sofa.class, "ektorp");
sofa.setColor("blue");
db.update(sofa);

Ektorp features a generic repository support class. It provides all Create, Read, Update and Delete operations for a persistent class.

Here's how a SofaRepository implemented with the generic repository looks like

public class SofaRepository extends CouchDbRepositorySupport<Sofa> {

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

This repository will have the following methods "out of the box":

SofaRepository repo = new SofaRepository(db);
		
repo.add(Sofa s);
repo.contains("doc_id");
Sofa sofa = repo.get("doc_id");
repo.update(Sofa s);
repo.remove(Sofa s);
List<Sofa> repo.getAll();

The concept of views in CouchDB can be a little daunting at first and there will always be the task of managing view definitions to go along your mapped classes. Ektorp provides two solutions for this:

It is possible to embed view definitions in your repository classes through a @View annotation:

@View( name="complicated_view", file = "complicated_view.json")
public class BlogPostRepository extends CouchDbRepositorySupport<BlogPost> {

    @Autowired
    public BlogPostRepository(@Qualifier("blogPostDatabase") CouchDbConnector db) {
            super(BlogPost.class, db);
            initStandardDesignDocument();
    }

    @Override
    @View( name="all", map = "function(doc) { if (doc.title) { emit(doc.dateCreated, doc._id) } }")
    public List<BlogPost> getAll() {
            ViewQuery q = createQuery("all").descending(true);
            return db.queryView(q, BlogPost.class);
    }
    
    @GenerateView
    public List<BlogPost> findByTag(String tag) {
            return queryView("by_tag", tag);
    }

}

Finder methods annotated with @GenerateView will have their view definitions automatically created. CouchDbRepositorySupport will generate a "by_tag" view in CouchDB at application start up for the method "findByTag" in the example above.

The JSON / Object mapping in Ektorp is handled by the excellent [http://wiki.fasterxml.com/JacksonHome Jackson JSON library].

Jackson makes it easy to map the common cases and provides for instance the possibility to map polymorph types for more advanced use cases.

All persistent objects managed by Ektorp need define properties for id and revision and they need to be accessible by getters and setters.

Here's an trivial example class:

import org.codehaus.jackson.annotate.*;

@JsonWriteNullProperties(false)
@JsonIgnoreProperties({"id", "revision"})
public class Sofa {

	@JsonProperty("_id")
	private String id;

        @JsonProperty("_rev")
	private String revision;

	private String color;

        public String setId(String s) {
		id = s;
	}

	public String getId() {
		return id;
	}

	public String getRevision() {
		return rev;
	}

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

	public String getColor() {
		return color;
	}
}

There are several methods for querying CouchDB [http://wiki.apache.org/couchdb/Introduction_to_CouchDB_views views] from Ektorp.

If the view's result value field is a document, Ektorp can load the result as a List of Objects

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. Currently just String and int values are supported.

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 most flexible method is query for stream. The result is returned as a stream.

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

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

If you want to learn more about Ektorp you can download the [http://code.google.com/p/ektorp/downloads/detail?name=org.ektorp.sample-1.6-project.zip sample application] and read the [http://ektorp.org/tutorial.html tutorial]. Or you can dive straight into the [http://www.ektorp.org/reference_documentation.html reference documentation]