[Couchdb Wiki] Update of "How to intercept document updates and perform additional server-side processing" by Ning Tan

[Apache Wiki]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for 
change notification.

The following page has been changed by Ning Tan:
http://wiki.apache.org/couchdb/How_to_intercept_document_updates_and_perform_additional_server-side_processing

New page:
== Basics ==

CouchDB (0.10 and up) has the ability to allow server-side processing of an 
incoming document before it's committed. This feature allows a range of use 
cases such as providing a server-side last modified timestamp, etc.

== Implementation ==

This functionality is implemented via document update handlers defined in a 
design doc. Specifically, in a design doc one defines an "updates" attribute 
that contains any number of document update handlers. The follow handlers 
should be self-explanatory as to what they accomplish. 

{{{
    updates: {

      "hello" : function(doc, req) {
        if (!doc) {
          if (req.docId) {
            return [{
              _id : req.docId
            }, "New World"]
          }
          return [null, "Empty World"];          
        }
        doc.world = "hello";
        doc.edited_by = req.userCtx;
        return [doc, "hello doc"];
      },

      "in-place" : function(doc, req) {
        var field = req.query.field;
        var value = req.query.value;
        var message = "set "+field+" to "+value;
        doc[field] = value;
        return [doc, message];
      },

      "bump-counter" : function(doc, req) {
        if (!doc.counter) doc.counter = 0;
        doc.counter += 1;
        var message = "<h1>bumped it!</h1>";
        return [doc, message];
      },

      "error" : function(doc, req) {
        superFail.badCrash;
      },

      "xml" : function(doc, req) {
        var xml = new XML('<xml></xml>');
        xml.title = doc.title;
        var posted_xml = new XML(req.body);
        doc.via_xml = posted_xml.foo.toString();
        var resp =  {
          "headers" : {
            "Content-Type" : "application/xml"
          },
          "body" : xml
        };
         
         return [doc, resp];
       }
    }
}}}

The handler function takes the document and the http request as parameters. It 
returns a two-element array: the first element is the (updated) document, which 
is committed to the database. The second element is the response that will be 
sent back to the caller.

== Usage ==

To invoke a handler, one must "put" the document against the handler function 
itself. Using the canonical document URL won't invoke any handlers. For 
example, to invoke the "in-place" handler defined above, the URL to use is:

{{{
http://127.0.0.1:5984/<my_database>/_design/<my_designdoc>/_update/in-place/<mydocId>?field=title&value=test
}}}

This usage seems to indicate that unlike document validators, the user's intend 
must be clear by calling an individual handler explicitly.