Java Views

Java Views

Overview

Barista allows a developer to author MapReduce using a familiar Java language, as well as enable you to leverage any existing Java libraries you may already have.

Note that Barista does NOT enforce any idempotency limitations, hence any reliance upon functionality defined outside of the installed Classpath through external services is potentially unsafe and may produce unexpected results. It is advised that all functionality used to define MapReduce to only access functionality defined/deployed in Java Archive attachments to a single CouchDB document.

General Design

CouchDB View Server API uses a serial approach to processing documents against map and reduce functions. Each implementation of MapDoc and Reduce interfaces executes within independent classloaders. While you may implement both MapDoc and Reduce within the same class, each interface will be executed in different classloaders. MapDoc and Reduce implementations should operate in a stateless manner, and NEVER rely upon or use output of a previous invocation or a globally static state.

The Base View

com.sri.learningregistry.couchdb.viewserver.interfaces.BaseView defines some basic general purpose utility functions that simplify emitting and logging from within your implementation.

public class BaseView {
	public JSONArray emit(Object key, Object value) {
		JSONArray arr = new JSONArray();
		arr.put(key);
		arr.put(value);
		return arr;
	}
	
	public void log(String message) {
		JSONArray array = new JSONArray();
		array.put("log");
		array.put(message);
		System.out.println(array.toString());
		System.out.flush();
	}
}

Map Functions

To implement a map function in Java, you will need to implement com.sri.learningregistry.couchdb.viewserver.interfaces.MapDoc

public interface MapDoc {
	public JSONArray map_doc( JSONObject doc );
}

Your implementation of MapDoc should follow the same structure as defined here

Reduce Functions (ALPHA - untested)

Similar to a map function, you will need to implement com.sri.learningregistry.couchdb.viewserver.interfaces.Reduce

public interface Reduce {
	/***
	 * 
	 * @param key_id_value an array of [[key, id-of-doc], value]
	 * @return
	 */
	public Object reduce(JSONArray key_id_value, boolean rereduce);
}

The definitive guide to what reduce should return can be found here

View installation

The installation of a Java View requires you in upload one or more JAR files, which will appear on your MapDoc and Reduce implementations' classpath, to a single CouchDB document. For details on how to upload attachments to a document in CouchDB, see the HTTP Document API on the CouchDB wiki.

{
   "_id": "classpath",
   "_rev": "1-c8d0fbe0d3be5d3cb6d09ba12318ffb2",
   "_attachments": {
       "views.jar": {
           "content_type": "application/octect-stream",
           "revpos": 1,
           "digest": "md5-nIXLMdXd9ddDodKmW8wZUg==",
           "length": 958219,
           "stub": true
       }
   }
}

Once you have uploaded all your JAR files that your MapDoc and Reduce implementations will need to access. You will need to install a CouchDB design document that references the classname and the classpath within the respective CouchDB design document's view map and reduce strings. The JSON for Map and Reduce are the same:

{
  "classpath": [
    "http://127.0.0.1:5984/java/classpath/views.jar"
  ],
  "classname": "com.sri.learningregistry.couchdb.views.SampleView",
  "rev": "1-c8d0fbe0d3be5d3cb6d09ba12318ffb2"
}

• classpath is a list of URL's to each JAR attachment. URL's should be in the format: protocol://login:password@servername:port/database/document/attachment.jar

• classname is the name of the MapDoc or Reduce implementation that will be instanced.

• rev is the CouchDB revision number of the document that contains the JAR attachments, hence all JAR's should reside within the same CouchDB document as to refer to a single revision number.

NB: The classpath parameter may change in a future version to omit protocol://login:password@/database so that access to remote jars can be better secured, these values would be relocated settings at View Server configuration

The Map and Reduce view definition within the CouchDB design document should be JavaScript escaped as a string as illustrated here:

{
   "_id": "_design/java",
   "_rev": "1-b6e265e1f9677938116b1db8fd1a3385",
   "language": "java",
   "views": {
       "xmlvalidate": {
           "map": "{\"classpath\":[\"http://127.0.0.1:5984/java/classpath/views.jar\"],\"rev\":\"1-c8d0fbe0d3be5d3cb6d09ba12318ffb2\",\"classname\":\"com.sri.learningregistry.couchdb.views.XMLSchemaValidationView\"}"
       },
       "simple": {
           "map": "{\"classpath\":[\"http://127.0.0.1:5984/java/classpath/views.jar\"],\"rev\":\"1-c8d0fbe0d3be5d3cb6d09ba12318ffb2\",\"classname\":\"com.sri.learningregistry.couchdb.views.SampleView\"}"
       }
   }
}