mirror of https://gitee.com/bigwinds/arangodb
311 lines
10 KiB
JavaScript
311 lines
10 KiB
JavaScript
/*jslint indent: 2, nomen: true, maxlen: 100, sloppy: true, vars: true, white: true, plusplus: true */
|
|
/*global require, TRANSACTION */
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief transaction actions
|
|
///
|
|
/// @file
|
|
///
|
|
/// DISCLAIMER
|
|
///
|
|
/// Copyright 2012 triagens GmbH, Cologne, Germany
|
|
///
|
|
/// Licensed under the Apache License, Version 2.0 (the "License");
|
|
/// you may not use this file except in compliance with the License.
|
|
/// You may obtain a copy of the License at
|
|
///
|
|
/// http://www.apache.org/licenses/LICENSE-2.0
|
|
///
|
|
/// Unless required by applicable law or agreed to in writing, software
|
|
/// distributed under the License is distributed on an "AS IS" BASIS,
|
|
/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
/// See the License for the specific language governing permissions and
|
|
/// limitations under the License.
|
|
///
|
|
/// Copyright holder is triAGENS GmbH, Cologne, Germany
|
|
///
|
|
/// @author Jan Steemann
|
|
/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
var arangodb = require("org/arangodb");
|
|
var actions = require("org/arangodb/actions");
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- private functions
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @addtogroup ArangoAPI
|
|
/// @{
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief execute a server-side transaction
|
|
///
|
|
/// @RESTHEADER{POST /_api/transaction,executes a transaction}
|
|
///
|
|
/// @RESTBODYPARAM{body,string,required}
|
|
/// Contains the `collections` and `action`.
|
|
///
|
|
/// @RESTDESCRIPTION
|
|
///
|
|
/// The transaction description must be passed in the body of the POST request.
|
|
///
|
|
/// The following attributes must be specified inside the JSON object:
|
|
///
|
|
/// - `collections`: contains the list of collections to be used in the
|
|
/// transaction (mandatory). `collections` must be a JSON array that can
|
|
/// have the optional sub-attributes `read` and `write`. `read`
|
|
/// and `write` must each be either lists of collections names or strings
|
|
/// with a single collection name.
|
|
///
|
|
/// - `action`: the actual transaction operations to be executed, in the
|
|
/// form of stringified Javascript code. The code will be executed on server
|
|
/// side, with late binding. It is thus critical that the code specified in
|
|
/// `action` properly sets up all the variables it needs.
|
|
/// If the code specified in `action` ends with a return statement, the
|
|
/// value returned will also be returned by the REST API in the `result`
|
|
/// attribute if the transaction committed successfully.
|
|
///
|
|
/// The following optional attributes may also be specified in the request:
|
|
///
|
|
/// - `waitForSync`: an optional boolean flag that, if set, will force the
|
|
/// transaction to write all data to disk before returning.
|
|
///
|
|
/// - `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 `lockTimeout` to `0` will make ArangoDB
|
|
/// not time out waiting for a lock.
|
|
///
|
|
/// - `replicate`: whether or not to replicate the operations from this
|
|
/// transaction. If not specified, the default value is `true`.
|
|
///
|
|
/// - `params`: optional arguments passed to `action`.
|
|
///
|
|
/// If the transaction is fully executed and committed on the server,
|
|
/// `HTTP 200` will be returned. Additionally, the return value of the
|
|
/// code defined in `action` will be returned in the `result` attribute.
|
|
///
|
|
/// For successfully committed transactions, the returned JSON object has the
|
|
/// following properties:
|
|
///
|
|
/// - `error`: boolean flag to indicate if an error occurred (`false`
|
|
/// in this case)
|
|
///
|
|
/// - `code`: the HTTP status code
|
|
///
|
|
/// - `result`: the return value of the transaction
|
|
///
|
|
/// If the transaction specification is either missing or malformed, the server
|
|
/// will respond with `HTTP 400`.
|
|
///
|
|
/// The body of the response will then contain a JSON object with additional error
|
|
/// details. The object has the following attributes:
|
|
///
|
|
/// - `error`: boolean flag to indicate that an error occurred (`true` in this case)
|
|
///
|
|
/// - `code`: the HTTP status code
|
|
///
|
|
/// - `errorNum`: the server error number
|
|
///
|
|
/// - `errorMessage`: a descriptive error message
|
|
///
|
|
/// If a transaction fails to commit, either by an exception thrown in the
|
|
/// `action` code, or by an internal error, the server will respond with
|
|
/// an error.
|
|
/// Any other errors will be returned with any of the return codes
|
|
/// `HTTP 400`, `HTTP 409`, or `HTTP 500`.
|
|
///
|
|
/// @RESTRETURNCODES
|
|
///
|
|
/// @RESTRETURNCODE{200}
|
|
/// If the transaction is fully executed and committed on the server,
|
|
/// `HTTP 200` will be returned.
|
|
///
|
|
/// @RESTRETURNCODE{400}
|
|
/// If the transaction specification is either missing or malformed, the server
|
|
/// will respond with `HTTP 400`.
|
|
///
|
|
/// @RESTRETURNCODE{500}
|
|
/// Exceptions thrown by users will make the server respond with a return code of
|
|
/// `HTTP 500`
|
|
///
|
|
/// @EXAMPLES
|
|
///
|
|
/// Executing a transaction on a single collection:
|
|
///
|
|
/// @EXAMPLE_ARANGOSH_RUN{RestTransactionSingle}
|
|
/// var cn = "products";
|
|
/// db._drop(cn);
|
|
/// var products = db._create(cn);
|
|
/// var url = "/_api/transaction";
|
|
/// var body = {
|
|
/// collections: {
|
|
/// write : "products"
|
|
/// },
|
|
/// action: "function () { " +
|
|
/// "var db = require('internal').db; " +
|
|
/// "db.products.save({}); " +
|
|
/// "return db.products.count(); }"
|
|
/// };
|
|
///
|
|
/// var response = logCurlRequest('POST', url, body);
|
|
/// assert(response.code === 200);
|
|
///
|
|
/// logJsonResponse(response);
|
|
/// db._drop(cn);
|
|
/// @END_EXAMPLE_ARANGOSH_RUN
|
|
///
|
|
/// Executing a transaction using multiple collections:
|
|
///
|
|
/// @EXAMPLE_ARANGOSH_RUN{RestTransactionMulti}
|
|
/// var cn1 = "materials";
|
|
/// db._drop(cn1);
|
|
/// var materials = db._create(cn1);
|
|
/// var cn2 = "products";
|
|
/// db._drop(cn2);
|
|
/// var products = db._create(cn2);
|
|
/// products.save({ "a": 1});
|
|
/// materials.save({ "b": 1});
|
|
/// var url = "/_api/transaction";
|
|
/// var body = {
|
|
/// collections: {
|
|
/// write : [ "products", "materials" ]
|
|
/// },
|
|
/// action: "function () { " +
|
|
/// "var db = require('internal').db; " +
|
|
/// "db.products.save({}); " +
|
|
/// "db.materials.save({}); " +
|
|
/// "return 'worked!'; }"
|
|
/// };
|
|
///
|
|
/// var response = logCurlRequest('POST', url, body);
|
|
/// assert(response.code === 200);
|
|
///
|
|
/// logJsonResponse(response);
|
|
/// db._drop(cn1);
|
|
/// db._drop(cn2);
|
|
/// @END_EXAMPLE_ARANGOSH_RUN
|
|
///
|
|
/// Aborting a transaction due to an internal error:
|
|
///
|
|
/// @EXAMPLE_ARANGOSH_RUN{RestTransactionAbortInternal}
|
|
/// var cn = "products";
|
|
/// db._drop(cn);
|
|
/// var products = db._create(cn);
|
|
/// var url = "/_api/transaction";
|
|
/// var body = {
|
|
/// collections: {
|
|
/// write : "products"
|
|
/// },
|
|
/// action : "function () { " +
|
|
/// "var db = require('internal').db; " +
|
|
/// "db.products.save({ _key: 'abc'}); " +
|
|
/// "db.products.save({ _key: 'abc'}); }"
|
|
/// };
|
|
///
|
|
/// var response = logCurlRequest('POST', url, body);
|
|
/// assert(response.code === 400);
|
|
///
|
|
/// logJsonResponse(response);
|
|
/// db._drop(cn);
|
|
/// @END_EXAMPLE_ARANGOSH_RUN
|
|
///
|
|
/// Aborting a transaction by explicitly throwing an exception:
|
|
///
|
|
/// @EXAMPLE_ARANGOSH_RUN{RestTransactionAbort}
|
|
/// var cn = "products";
|
|
/// db._drop(cn);
|
|
/// var products = db._create(cn, { waitForSync: true });
|
|
/// products.save({ "a": 1 });
|
|
/// var url = "/_api/transaction";
|
|
/// var body = {
|
|
/// collections: {
|
|
/// read : "products"
|
|
/// },
|
|
/// action : "function () { throw 'doh!'; }"
|
|
/// };
|
|
///
|
|
/// var response = logCurlRequest('POST', url, body);
|
|
/// assert(response.code === 500);
|
|
///
|
|
/// logJsonResponse(response);
|
|
/// db._drop(cn);
|
|
/// @END_EXAMPLE_ARANGOSH_RUN
|
|
///
|
|
/// Referring to a non-existing collection:
|
|
///
|
|
/// @EXAMPLE_ARANGOSH_RUN{RestTransactionNonExisting}
|
|
/// var cn = "products";
|
|
/// db._drop(cn);
|
|
/// var url = "/_api/transaction";
|
|
/// var body = {
|
|
/// collections: {
|
|
/// read : "products"
|
|
/// },
|
|
/// action : "function () { return true; }"
|
|
/// };
|
|
///
|
|
/// var response = logCurlRequest('POST', url, body);
|
|
/// assert(response.code === 404);
|
|
///
|
|
/// logJsonResponse(response);
|
|
/// @END_EXAMPLE_ARANGOSH_RUN
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
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 });
|
|
}
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// -----------------------------------------------------------------------------
|
|
// --SECTION-- initialiser
|
|
// -----------------------------------------------------------------------------
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @brief gateway
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
actions.defineHttp({
|
|
url : "_api/transaction",
|
|
context : "api",
|
|
|
|
callback : function (req, res) {
|
|
try {
|
|
switch (req.requestType) {
|
|
case actions.POST:
|
|
post_api_transaction(req, res);
|
|
break;
|
|
|
|
default:
|
|
actions.resultUnsupported(req, res);
|
|
}
|
|
}
|
|
catch (err) {
|
|
actions.resultException(req, res, err);
|
|
}
|
|
}
|
|
});
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
/// @}
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Local Variables:
|
|
// mode: outline-minor
|
|
// outline-regexp: "^\\(/// @brief\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @}\\)"
|
|
// End:
|