From 0f9425cc2477f31d68c23e81c144b450b35bbb78 Mon Sep 17 00:00:00 2001 From: kay Date: Mon, 25 Mar 2013 11:31:56 -0400 Subject: [PATCH] DOCS-1284 single source eval content; make explicit relationship btwn command and helper --- source/includes/admonitions-eval.rst | 24 ++++ source/includes/examples-eval.rst | 38 ++++++ source/includes/fact-eval-helper-method.rst | 5 + source/includes/parameters-eval.rst | 32 +++++ source/reference/command/eval.txt | 128 +++++--------------- source/reference/method/db.eval.txt | 86 +++---------- source/reference/user-privileges.txt | 7 +- 7 files changed, 152 insertions(+), 168 deletions(-) create mode 100644 source/includes/admonitions-eval.rst create mode 100644 source/includes/examples-eval.rst create mode 100644 source/includes/fact-eval-helper-method.rst create mode 100644 source/includes/parameters-eval.rst diff --git a/source/includes/admonitions-eval.rst b/source/includes/admonitions-eval.rst new file mode 100644 index 00000000000..7521415043b --- /dev/null +++ b/source/includes/admonitions-eval.rst @@ -0,0 +1,24 @@ +.. warning:: + + .. \|object| defined in included parameters-eval .. + .. \|nolockobject| defined in included parameters-eval .. + + - .. include:: /includes/fact-eval-lock.rst + + - Do not use |object| for long running operations as + |object| blocks all other operations. Consider using + :doc:`other server side code execution options + `. + + - You can not use |object| with :term:`sharded + ` data. In general, you should avoid using + |object| in :term:`sharded cluster`; nevertheless, it + is possible to use |object| with non-sharded + collections and databases stored in a :term:`sharded cluster`. + + - .. include:: /includes/fact-eval-authentication.rst + +.. versionchanged:: 2.4 + The V8 JavaScript engine, which became the default in 2.4, allows + multiple JavaScript operations to execute at the same time. Prior to + 2.4, |object| executed in a single thread. diff --git a/source/includes/examples-eval.rst b/source/includes/examples-eval.rst new file mode 100644 index 00000000000..23f6d170cb9 --- /dev/null +++ b/source/includes/examples-eval.rst @@ -0,0 +1,38 @@ +.. eval-command-example + +.. code-block:: javascript + + db.runCommand( { + eval: function(name, incAmount) { + var doc = db.myCollection.findOne( { name : name } ); + + doc = doc || { name : name , num : 0 , total : 0 , avg : 0 }; + + doc.num++; + doc.total += incAmount; + doc.avg = doc.total / doc.num; + + db.myCollection.save( doc ); + return doc; + }, + args: [ "eliot", 5 ] + } + ); + +.. eval-method-example + +.. code-block:: javascript + + db.eval( function(name, incAmount) { + var doc = db.myCollection.findOne( { name : name } ); + + doc = doc || { name : name , num : 0 , total : 0 , avg : 0 }; + + doc.num++; + doc.total += incAmount; + doc.avg = doc.total / doc.num; + + db.myCollection.save( doc ); + return doc; + }, + "eliot", 5 ); diff --git a/source/includes/fact-eval-helper-method.rst b/source/includes/fact-eval-helper-method.rst new file mode 100644 index 00000000000..aedc2a10066 --- /dev/null +++ b/source/includes/fact-eval-helper-method.rst @@ -0,0 +1,5 @@ +The shell helper :method:`db.eval()` acts as a wrapper around the +:dbcommand:`eval` command. As such, the helper method shares the +characteristics and behavior of the underlying command itself with the +*one exception* in that the :method:`db.eval()` method does not support +the ``nolock`` option. diff --git a/source/includes/parameters-eval.rst b/source/includes/parameters-eval.rst new file mode 100644 index 00000000000..8259fc1c733 --- /dev/null +++ b/source/includes/parameters-eval.rst @@ -0,0 +1,32 @@ +.. eval-param-function + +A JavaScript function. + +The function need not take any arguments, as in the first example, +or may take arguments as in the second: + +.. code-block:: javascript + + function () { + // ... + } + +.. code-block:: javascript + + function (arg1, arg2) { + // ... + } + +.. eval-param-argument + +|list| of corresponding arguments to pass to the specified +JavaScript function if the function accepts arguments. Omit if the +function does not take arguments. + +.. eval-param-nolock + +Optional. + +.. |object| replace:: :dbcommand:`eval` +.. |nolockobject| replace:: :dbcommand:`eval` command +.. include:: /includes/fact-eval-lock.rst diff --git a/source/reference/command/eval.txt b/source/reference/command/eval.txt index 1ab31490c22..a0e4dff500e 100644 --- a/source/reference/command/eval.txt +++ b/source/reference/command/eval.txt @@ -21,90 +21,39 @@ eval } The command contains the following fields: - - :field JavaScript function: - - A JavaScript function. - - The function may accept no arguments, as in the following - example: - - .. code-block:: javascript - - function () { - // ... - } - - The function can also accept arguments, as in the following example: - - .. code-block:: javascript - - function (arg1, arg2) { - // ... - } - - :field arguments: - - A list of arguments to pass to the JavaScript ``function`` if - the function accepts arguments. Omit if the ``function`` does - not take arguments. + + :field function eval: + .. include:: /includes/parameters-eval.rst + :start-after: eval-param-function + :end-before: eval-param-argument :field array args: - An array of corresponding arguments to the ``function``. Omit - ``args`` if the ``function`` does not take arguments. + .. |list| replace:: An array + .. include:: /includes/parameters-eval.rst + :start-after: eval-param-argument + :end-before: eval-param-nolock - :field boolean nolock: Optional. + :field boolean nolock: - .. |object| replace:: :dbcommand:`eval` - .. |nolockobject| replace:: :dbcommand:`eval` command - .. include:: /includes/fact-eval-lock.rst + .. include:: /includes/parameters-eval.rst + :start-after: eval-param-nolock Consider the following example which uses :dbcommand:`eval` to perform an increment and calculate the average on the server: - .. code-block:: javascript - - db.runCommand( { - eval: function(name, incAmount) { - var doc = db.myCollection.findOne( { name : name } ); - - doc = doc || { name : name , num : 0 , total : 0 , avg : 0 }; - - doc.num++; - doc.total += incAmount; - doc.avg = doc.total / doc.num; - - db.myCollection.save( doc ); - return doc; - }, - args: [ "eliot", 5 ] - } - ); + .. include:: /includes/examples-eval.rst + :start-after: eval-command-example + :end-before: .. eval-method-example The ``db`` in the function refers to the current database. - The shell also provides a helper method :method:`db.eval()`, so you - can express the above as follows: - - .. code-block:: javascript - - db.eval( function(name, incAmount) { - var doc = db.myCollection.findOne( { name : name } ); - - doc = doc || { name : name , num : 0 , total : 0 , avg : 0 }; - - doc.num++; - doc.total += incAmount; - doc.avg = doc.total / doc.num; - - db.myCollection.save( doc ); - return doc; - }, - "eliot", 5 ); + The :program:`mongo` shell provides a helper method + :method:`db.eval()` [#eval-shell-helper]_, so you can express the + above as follows: - The :method:`db.eval()` method does not support the ``nolock`` - option. + .. include:: /includes/examples-eval.rst + :start-after: .. eval-method-example If you want to use the server's interpreter, you must run :dbcommand:`eval`. Otherwise, the :program:`mongo` shell's @@ -120,7 +69,7 @@ eval db.runCommand( { eval: function() { return x + x; }, - args: [3] + args: [ 3 ] } ) @@ -129,35 +78,16 @@ eval .. code-block:: javascript { - "errno" : -3, - "errmsg" : "invoke failed: JS Error: ReferenceError: x is not defined nofile_b:1", + "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ", + "code" : 16722, "ok" : 0 } - .. warning:: - - .. \|object| defined above .. - .. \|nolockobject| defined above .. - - - .. include:: /includes/fact-eval-lock.rst - - - Do not use :dbcommand:`eval` for long running operations as - :dbcommand:`eval` blocks all other operations. Consider using - :doc:`other server side code execution options - `. - - - You can not use :dbcommand:`eval` with :term:`sharded - ` data. In general, you should avoid using - :dbcommand:`eval` in :term:`sharded cluster`; nevertheless, it - is possible to use :dbcommand:`eval` with non-sharded - collections and databases stored in a :term:`sharded cluster`. - - - .. include:: /includes/fact-eval-authentication.rst - - .. versionchanged:: 2.4 - The V8 JavaScript engine, which became the default in 2.4, allows - multiple JavaScript operations to execute at the same - time. Prior to 2.4, :dbcommand:`eval` executed in a single - thread. + .. \|object| defined in included parameters-eval .. + .. \|nolockobject| defined in included parameters-eval .. + .. include:: /includes/admonitions-eval.rst .. seealso:: :doc:`/applications/server-side-javascript` + + .. [#eval-shell-helper] + .. include:: /includes/fact-eval-helper-method.rst diff --git a/source/reference/method/db.eval.txt b/source/reference/method/db.eval.txt index 53f498b44aa..ae42a02ae9e 100644 --- a/source/reference/method/db.eval.txt +++ b/source/reference/method/db.eval.txt @@ -10,59 +10,32 @@ db.eval() .. method:: db.eval(function, arguments) The :method:`db.eval()` provides the ability to run JavaScript code - on the MongoDB server. It is a :program:`mongo` shell wrapper around - the :dbcommand:`eval` command. However, unlike the :dbcommand:`eval` - command, the :method:`db.eval()` method does not support the - ``nolock`` option. + on the MongoDB server. + + .. include:: /includes/fact-eval-helper-method.rst The method accepts the following parameters: :param JavaScript function: - - A JavaScript function. - - The function need not take any arguments, as in the first - example, or may optionally take arguments as in the second: - - .. code-block:: javascript - - function () { - // ... - } - - .. code-block:: javascript - - function (arg1, arg2) { - // ... - } + .. include:: /includes/parameters-eval.rst + :start-after: eval-param-function + :end-before: eval-param-argument :param arguments: - A list of arguments to pass to the JavaScript ``function`` if - the function accepts arguments. Omit if the ``function`` does - not take arguments. + .. |list| replace:: A list + .. include:: /includes/parameters-eval.rst + :start-after: eval-param-argument + :end-before: eval-param-nolock Consider the following example of the :method:`db.eval()` method: - .. code-block:: javascript - - db.eval( function(name, incAmount) { - var doc = db.myCollection.findOne( { name : name } ); - - doc = doc || { name : name , num : 0 , total : 0 , avg : 0 }; - - doc.num++; - doc.total += incAmount; - doc.avg = doc.total / doc.num; - - db.myCollection.save( doc ); - return doc; - }, - "", 5 ); + .. include:: /includes/examples-eval.rst + :start-after: .. eval-method-example - The ``db`` in the function refers to the current database. - - ``""`` is the argument passed to the function, and + - ``"eliot"`` is the argument passed to the function, and corresponds to the ``name`` argument. - ``5`` is an argument to the function and corresponds to the @@ -86,37 +59,14 @@ db.eval() .. code-block:: javascript { - "errno" : -3, - "errmsg" : "invoke failed: JS Error: ReferenceError: x is not defined nofile_b:1", + "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ", + "code" : 16722, "ok" : 0 } - .. warning:: - - .. |object| replace:: :method:`db.eval()` - - .. |nolockobject| replace:: :dbcommand:`eval` *command* - - - .. include:: /includes/fact-eval-lock.rst - - - Do not use :method:`db.eval()` for long running operations, as - :method:`db.eval()` blocks all other operations. Consider using - :doc:`other server side code execution options - `. - - - You can not use :method:`db.eval()` with :term:`sharded - ` data. In general, you should avoid using - :method:`db.eval()` in :term:`sharded cluster`; nevertheless, - it is possible to use :method:`db.eval()` with non-sharded - collections and databases stored in :term:`sharded cluster`. - - - .. include:: /includes/fact-eval-authentication.rst - - .. versionchanged:: 2.4 - The V8 JavaScript engine, which became the default in 2.4, allows - multiple JavaScript operations to execute at the same - time. Prior to 2.4, :method:`db.eval()` executed in a single - thread. + .. |object| replace:: :method:`db.eval()` + .. |nolockobject| replace:: :dbcommand:`eval` *command* + .. include:: /includes/admonitions-eval.rst .. seealso:: diff --git a/source/reference/user-privileges.txt b/source/reference/user-privileges.txt index 127e029866d..5e17d4aa8c1 100644 --- a/source/reference/user-privileges.txt +++ b/source/reference/user-privileges.txt @@ -272,7 +272,12 @@ roles. Consider the following: Requires :authrole:`clusterAdmin` and :authrole:`read` access to the :data:`config` database. -:dbcommand:`applyOps`, :dbcommand:`eval`, and :method:`db.eval()` +:dbcommand:`applyOps`, :dbcommand:`eval` [#eval-shell-helper]_ Requires :authrole:`readAnyDatabase`, :authrole:`readWriteAnyDatabase`, :authrole:`userAdminAnyDatabase`, :authrole:`dbAdminAnyDatabase` and :authrole:`clusterAdmin` (on the ``admin`` database.) + +.. [#eval-shell-helper] The :program:`mongo` shell provides the shell + helper method :method:`db.eval()` for the :dbcommand:`eval` command. + As a wrapper, the method will require the same access requirements + as the command itself.