added documentation for transaction REST API

Documentation/Examples/api-transaction-abort

@@ -0,0 +1,7 @@
+> curl --data @- -X POST --dump - http://localhost:8529/_api/transaction
+{ "collections" : { "read" : "users" }, "action" : "throw \"doh!\";" }
+
+HTTP/1.1 500 Internal Error
+content-type: application/json; charset=utf-8
+
+{ "error" : true, "code" : 500, "errorNum" : 500, "errorMessage" : "doh!" }

Documentation/Examples/api-transaction-abort-internal

@@ -0,0 +1,7 @@
+> curl --data @- -X POST --dump - http://localhost:8529/_api/transaction
+{ "collections" : { "write" : [ "users" ] }, "action" : "var users = require(\"internal\").db.users; users.save({ _key: \"abc\" }); users.save({ _key: \"abc\" });" }
+
+HTTP/1.1 400 Bad Request
+content-type: application/json; charset=utf-8
+
+{ "error" : true, "code" : 400, "errorNum" : 1210, "errorMessage" : "cannot save document: unique constraint violated" } 

Documentation/Examples/api-transaction-multi

@@ -0,0 +1,7 @@
+> curl --data @- -X POST --dump - http://localhost:8529/_api/transaction
+{ "collections" : { "write" : [ "users", "logins" ] }, "action" : "var users = require(\"internal\").db.users; var logins = require(\"internal\").db.logins; users.save({ }); logins.save({ }); return \"worked!\";" }
+
+HTTP/1.1 200 OK
+content-type: application/json; charset=utf-8
+
+{ "result" : "worked!", "error" : false, "code" : 200 }

Documentation/Examples/api-transaction-single

@@ -0,0 +1,7 @@
+> curl --data @- -X POST --dump - http://localhost:8529/_api/transaction
+{ "collections" : { "write" : "users" }, "action" : "var users = require(\"internal\").db.users; users.save({ _key: \"hello\" }); return users.count();" }
+
+HTTP/1.1 200 OK
+content-type: application/json; charset=utf-8
+
+{ "result" : 1, "error" : false, "code" : 200 }

Documentation/ImplementorManual/HttpTransactions.md

@@ -0,0 +1,31 @@
+HTTP Interface for Transactions {#HttpTransactions}
+===================================================
+
+@NAVIGATE_HttpTransactions
+@EMBEDTOC{HttpTransactionsTOC}
+
+Transactions {#HttpTransactionsIntro}
+=====================================
+
+ArangoDB's transactions are executed on the server. Transactions can be 
+initiated by clients by sending the transaction description for execution to
+the server.
+
+Transactions in ArangoDB do not offer seperate `BEGIN`, `COMMIT` and `ROLLBACK`
+operations as they are available in many other database products. 
+Instead, ArangoDB transactions are described by a Javascript function, and the 
+code inside the Javascript function will then be executed transactionally.
+At the end of the function, the transaction is automatically committed, and all
+changes done by the transaction will be persisted. If an exception is thrown
+during transaction execution, all operations performed in the transaction are
+rolled back.
+
+For a more detailed description of how transactions work in ArangoDB please
+refer to @ref Transactions. 
+
+Executing Transactions via HTTP {#HttpTransactionsHttp}
+=======================================================
+
+@anchor HttpTransactionsPost
+@copydetails JSF_POST_api_transaction
+

Documentation/ImplementorManual/HttpTransactionsTOC.md

@@ -0,0 +1,7 @@
+TOC {#HttpTransactionsTOC}
+==========================
+
+- @ref HttpTransactions
+  - @ref HttpTransactionsIntro
+  - @ref HttpTransactionsHttp
+    - @ref HttpTransactionsPost "POST /_api/transactions"

Documentation/Makefile.files

@@ -37,11 +37,13 @@ DOXYGEN = \
 	Doxygen/js/actions/api-cursor.c \
 	Doxygen/js/actions/api-edges.c \
 	Doxygen/js/actions/api-explain.c \
+	Doxygen/js/actions/api-foxx.c \
 	Doxygen/js/actions/api-graph.c \
 	Doxygen/js/actions/api-index.c \
 	Doxygen/js/actions/api-query.c \
 	Doxygen/js/actions/api-simple.c \
 	Doxygen/js/actions/api-system.c \
+	Doxygen/js/actions/api-transaction.c \
 	Doxygen/js/actions/api-user.c \
 	Doxygen/js/common/bootstrap/module-console.c \
 	Doxygen/js/common/bootstrap/module-fs.c \
@@ -93,6 +95,7 @@ WIKI = \
 	HttpQuery \
 	HttpSimple \
 	HttpSystem \
+	HttpTransactions \
 	HttpUser \
 	ImpManual \
 	ImpManualBasics \

js/actions/api-cursor.js

@@ -135,6 +135,7 @@ function POST_api_cursor(req, res) {
   var json = actions.getJsonBody(req, res);
 
   if (json === undefined) {
+    actions.resultBad(req, res, arangodb.ERROR_QUERY_EMPTY);
     return;
   }
 

js/actions/api-transaction.js

@@ -25,6 +25,7 @@
 /// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
 ////////////////////////////////////////////////////////////////////////////////
 
+var arangodb = require("org/arangodb");
 var actions = require("org/arangodb/actions");
 
 // -----------------------------------------------------------------------------
@@ -58,8 +59,8 @@ var actions = require("org/arangodb/actions");
 ///
 /// - @LIT{lockTimeout}: an optional numeric value that can be used to set a
 ///   timeout for waiting on collection locks. If not specified, a default 
-///   value will be used. Setting @LIT{lockTimeout} to 0 will make ArangoDB not
+///   value will be used. Setting @LIT{lockTimeout} to @LIT{0} will make ArangoDB 
-///   time out waiting for a lock.
+///   not time out waiting for a lock.
 ///
 /// - @LIT{action}: the actual transaction operations to be executed, in the
 ///   form of stringified Javascript code. The code will be executed on server
@@ -98,12 +99,39 @@ var actions = require("org/arangodb/actions");
 ///
 /// If a transaction fails to commit, either by an exception thrown in the 
 /// @LIT{action} code, or by an internal error, the server will respond with 
-/// @LIT{HTTP 500}.
+/// an error. 
+///
+/// Exceptions thrown by users will make the server respond with a return code of 
+/// @LIT{HTTP 500}. Any other errors will be returned with any of the return codes
+/// @LIT{HTTP 400}, @LIT{HTTP 409}, or @LIT{HTTP 500}.
+///
+/// @EXAMPLES
+///
+/// Executing a transaction on a single collection:
+///
+/// @verbinclude api-transaction-single
+///
+/// Executing a transaction using multiple collections:
+///
+/// @verbinclude api-transaction-multi
+///
+/// Aborting a transaction due to an internal error:
+///
+/// @verbinclude api-transaction-abort-internal
+///
+/// Aborting a transaction by throwing an exception:
+///
+/// @verbinclude api-transaction-abort
 ////////////////////////////////////////////////////////////////////////////////
 
 function POST_api_transaction(req, res) {
   var json = actions.getJsonBody(req, res);
 
+  if (json === undefined) {
+    actions.resultBad(req, res, arangodb.ERROR_HTTP_BAD_PARAMETER);
+    return;
+  }
+
   var result = TRANSACTION(json);
 
   actions.resultOk(req, res, actions.HTTP_OK, { "result" : result });