couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "Document_Update_Handlers" by ZacharyZolton
Date Tue, 28 Dec 2010 16:51:25 GMT
Dear Wiki user,

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

The "Document_Update_Handlers" page has been changed by ZacharyZolton.
The comment on this change is: Minor wordsmithing and linking to a relevant JIRA issue.
http://wiki.apache.org/couchdb/Document_Update_Handlers?action=diff&rev1=15&rev2=16

--------------------------------------------------

  <<TableOfContents()>>
  
  == Basics ==
- CouchDB (0.10 and up) has the ability to allow server-side updating of a document without
the usual GET-modify-POST cycle, or server-side creation of a new document based on parameters
sent by the user. This feature allows a range of use cases such as providing a server-side
last modified timestamp, updating individual fields in a document without first getting the
latest revision, etc.  This also allows for the CouchDB server to provide a GET-modify-POST
cycle that does not depend on client-side JS to create or edit documents.
+ Update handler are functions clients can request to invoke server-side logic that will create
or update a document. This feature allows a range of use cases such as providing a server-side
last modified timestamp, updating individual fields in a document without first getting the
latest revision, etc.
  
- The update handler can be passed a document id (via the URI( to show that it will be editing
that document, and the server will provide the function with the most recent version of that
document.  Anything else passed to the handler happens through the POST/PUT body or the query
string, and must be handled in the handler.
+ When the request to an update handler includes a document ID in the URL, the server will
provide the function with the most recent version of that document. You can provide any other
values needed by the update handler function via the POST/PUT entity body or query string
parameters of the request.
  
- == 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.
+ This feature was first implemented in CouchDB version 0.10.
+ 
+ == Creating an Update Handler ==
+ You can specify any number of update handler functions in a design document, under the "updates"
attribute.
+ 
+ For example:
  
  {{{#!highlight javascript
  {
@@ -67, +71 @@

    }
  }
  }}}
- NOTE: '''The functions should be quoted'''.
+ NOTE: '''The functions should be double-quoted JSON strings'''.
  
  The handler function takes the most recent version of the document from the database and
the http request environment as parameters. It returns a two-element array: the first element
is the (updated or new) document, which is committed to the database. If the first element
is null no document will be committed to the database. If you are updating an existing, it
should already have an `_id` set, and if you are creating a new document, make sure to set
its `_id` to something, either generated based on the input or the `req.uuid` provided. The
second element is the response that will be sent back to the caller.
  
@@ -76, +80 @@

  The request parameter will look something like this for a update function designed to create
a new document:
  
  {{{#!highlight javacript
+ {
-     {"info": 
+   "info": {
-     	{
-     		"db_name":"loot",
+     "db_name": "loot",
-     		/* and many more */
+     /* and many more */
-     		"committed_update_seq":27
+     "committed_update_seq": 27
-     	},
+   },
-     	"id":null,
+   "id": null,
-     	"uuid":"7f8a0e3833bcc7161cfab80275221dc1",
+   "uuid": "7f8a0e3833bcc7161cfab80275221dc1",
-     	"method":"POST",
+   "method": "POST",
-     	"path":["loot","_design","haul","_update","new"],
+   "path": ["loot", "_design", "haul", "_update", "new"],
-     	"query":{},
+   "query": {},
-     	"headers":{"Accept":"application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5"
/* and many more */},
+   "headers": {"Accept": "application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5"
/* and many more */},
-     	"body":"name=Jeff",
+   "body": "name=Jeff",
-     	"peer":"127.0.0.1",
+   "peer": "127.0.0.1",
-     	"form":{"name":"Jeff"},
+   "form": {"name": "Jeff"},
-     	"cookie":{},
+   "cookie": {},
-     	"userCtx":{"db":"loot","name":null,"roles":[]}
+   "userCtx": {"db": "loot", "name": null, "roles": []}
-     }
+ }
  }}}
  
- Since no ID was passed, the request doesn't have an ID.  However, the CouchDB server helpfully
throws in a UUID so you can create a new document with a unique ID and be sure it won't conflict
with any document in the database already.
+ Since no ID was passed, the request doesn't have an ID.  However, the CouchDB server helpfully
provides a UUID so you can create a new document with a unique ID and be sure it won't conflict
with any document in the database already.
  
  The server also parses the POST body into a Javascript object called `form` and does the
same with the query string, in `query`.
  
@@ -104, +108 @@

  The second member of the return array is the HTTP response. This can be a javascript object
with headers and a body:
  
  {{{#!highlight javascript
-     var resp =  {
+ var resp =  {
-       "headers" : {
+   "headers" : {
-         "Content-Type" : "application/xml"
+     "Content-Type" : "application/xml"
-       },
+   },
-       "body" : doc.xml
+   "body" : doc.xml
-     };
+ };
  }}}
  
  or just a plain string:
  {{{
      <p>Update function complete!</p>
  }}}
- Though you can set the headers, right now the status code for an update function response
is hardcoded to be 200/201 unless an error occurs.  This is a bug.
+ Though you can set the headers, right now the status code for an update function response
is hardcoded to be 200/201 unless an error occurs. See [[https://issues.apache.org/jira/browse/COUCHDB-648|this
issue]] in JIRA.
  
  
  == Usage ==
@@ -136, +140 @@

  
  For more information, look at ''update_documents.js'' in the test suite.
  
- == TBD ==
-  * Maybe we should support PATCH?
- 

Mime
View raw message