From a3917219374d57db8a9525b7388ac7c870b8b1d0 Mon Sep 17 00:00:00 2001 From: kay Date: Wed, 17 Oct 2012 17:42:51 -0400 Subject: [PATCH 1/5] DOCS-563,586 ObjectId() class methods and field doc --- source/applications.txt | 1 + source/core/ObjectId.txt | 87 +++++++++++++++++++ source/reference/method/ObjectId.toString.txt | 31 +++++++ source/reference/method/ObjectId.valueOf.txt | 29 +++++++ 4 files changed, 148 insertions(+) create mode 100644 source/core/ObjectId.txt create mode 100644 source/reference/method/ObjectId.toString.txt create mode 100644 source/reference/method/ObjectId.valueOf.txt diff --git a/source/applications.txt b/source/applications.txt index f9e2a45d04b..e440228baee 100644 --- a/source/applications.txt +++ b/source/applications.txt @@ -32,6 +32,7 @@ The following documents outline basic application development topics: applications/drivers applications/database-references + core/ObjectId .. seealso:: diff --git a/source/core/ObjectId.txt b/source/core/ObjectId.txt new file mode 100644 index 00000000000..155bad5062a --- /dev/null +++ b/source/core/ObjectId.txt @@ -0,0 +1,87 @@ +======== +ObjectId +======== + +:term:`ObjectId ` is a special :term:`BSON` type. It is a +12-byte value consisting of: + +- 4-byte timestamp +- 3-byte machine id +- 2-byte process id +- 3-byte counter + +In MongoDB, documents stored in collections must have an :term:`_id` +field. If a document is missing the ``_id`` field during a create +operation, the :program:`mongod` adds the ``_id`` field and generates a +unique ``ObjectId`` to assign as its value. + +ObjectId() +---------- + +MongoDB provides the ``ObjectId()`` wrapper class in the :program:`mongo` +shell. The ``ObjectId()`` class can generate a new ``ObjectId`` and provide +the following helper attribute and methods: + +.. glossary:: + + str + + the hexadecimal string value of the ObjectID() object. + + toString() + + returns the string representation of the ObjectId() object. The + returned string literal has the format "ObjectId(...)". + + Prior to version 2.2, returns the value of the object as a + hexadecmial string. + + valueOf() + + returns the value of the ObjectId() object as a hexadecimal string. + The returned string is the ``str`` attribute. + + Prior to version 2.2, returns the string literal "ObjectId(...)" + +Consider the following usage of the ObjectID() class in the :program:`mongo` +shell: + +- Generate a new ObjectId() using the constructor with no argument: + + .. code-block:: javascript + + > x=ObjectId() + + ObjectId("507f1f77bcf86cd799439011") + +- Generate a new ObjectId() using the constructor with a unique hexadecimal string: + + .. code-block:: javascript + + > y=ObjectId("507f191e810c19729de860ea") + + ObjectId("507f191e810c19729de860ea") + +- Access the ``str`` attribute of an ObjectId() object: + + .. code-block:: javascript + + > y.str + + 507f191e810c19729de860ea + +- Get the string representation of an ObjectId() object: + + .. code-block:: javascript + + > y.toString() + + ObjectId("507f191e810c19729de860ea") + +- Get the value of an ObjectId() object as a hexadecimal string: + + .. code-block:: javascript + + > y.valueOf() + + 507f191e810c19729de860ea diff --git a/source/reference/method/ObjectId.toString.txt b/source/reference/method/ObjectId.toString.txt new file mode 100644 index 00000000000..76e3abb309e --- /dev/null +++ b/source/reference/method/ObjectId.toString.txt @@ -0,0 +1,31 @@ +=================== +ObjectId.toString() +=================== + +.. default-domain:: mongodb + +.. method:: ObjectId.toString() + + .. versionchanged:: 2.2 + + Returns the string representation of the ObjectId() object and has the + format ``ObjectId(...)``. + + In the following example, the :method:`toString + ` method for + ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns the string literal + ``ObjectId("507c7f79bcf86cd7994f6c0e")``: + + .. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + ObjectId("507c7f79bcf86cd7994f6c0e") + + .. note:: + + Prior to version 2.2, the :method:`toString + ` method returns the value of the object as + a hexadecmial string, e.g. ``507c7f79bcf86cd7994f6c0e``. More + precisely, prior to version 2.2, the method returns the ``str`` + attribute of the ObjectId() object. diff --git a/source/reference/method/ObjectId.valueOf.txt b/source/reference/method/ObjectId.valueOf.txt new file mode 100644 index 00000000000..f5ad61c37c7 --- /dev/null +++ b/source/reference/method/ObjectId.valueOf.txt @@ -0,0 +1,29 @@ +================== +ObjectId.valueOf() +================== + +.. default-domain:: mongodb + +.. method:: ObjectId.valueOf() + + .. versionchanged:: 2.2 + + Returns the value of the ObjectId() object as a lowercase + hexadecimal string. More precisely, the method returns the ``str`` + attribute of the ObjectId() object. + + In the following example, the :method:`valueOf ` + method for ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns the + hexadecimal string ``507c7f79bcf86cd7994f6c0e``: + + .. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + 507c7f79bcf86cd7994f6c0e + + .. note:: + + Prior to version 2.2, :method:`valueOf ` + method returns the string literal, e.g. + ``ObjectId("507c7f79bcf86cd7994f6c0e")``. From be7abf071b82d9b18416cd60306edb08becc4896 Mon Sep 17 00:00:00 2001 From: kay Date: Wed, 17 Oct 2012 18:26:49 -0400 Subject: [PATCH 2/5] DOCS-563 and DOCS-586 edits to ObjectId doc --- source/core/ObjectId.txt | 50 +++++++++++++++++++++------------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/source/core/ObjectId.txt b/source/core/ObjectId.txt index 155bad5062a..d3332fc9a27 100644 --- a/source/core/ObjectId.txt +++ b/source/core/ObjectId.txt @@ -2,16 +2,20 @@ ObjectId ======== -:term:`ObjectId ` is a special :term:`BSON` type. It is a -12-byte value consisting of: +:term:`ObjectId ` is a 12-byte :term:`BSON` type that consists of: - 4-byte timestamp - 3-byte machine id - 2-byte process id - 3-byte counter -In MongoDB, documents stored in collections must have an :term:`_id` -field. If a document is missing the ``_id`` field during a create +In MongoDB, documents stored in a collection require a unique +:term:`_id` field that acts as a :term:`primary key`. Because +``ObjectIds`` are small, most likely unique, and fast to generate, +MongoDB uses ``ObjectIds`` as the default value for the ``_id`` field +if the ``_id`` field is not specified. + +If a document is missing the ``_id`` field during a create operation, the :program:`mongod` adds the ``_id`` field and generates a unique ``ObjectId`` to assign as its value. @@ -22,27 +26,25 @@ MongoDB provides the ``ObjectId()`` wrapper class in the :program:`mongo` shell. The ``ObjectId()`` class can generate a new ``ObjectId`` and provide the following helper attribute and methods: -.. glossary:: +- ``str`` - str - - the hexadecimal string value of the ObjectID() object. - - toString() - - returns the string representation of the ObjectId() object. The - returned string literal has the format "ObjectId(...)". - - Prior to version 2.2, returns the value of the object as a - hexadecmial string. + The hexadecimal string value of the ObjectID() object. + +- ``toString() `` + + Returns the string representation of the ObjectId() object. The + returned string literal has the format "ObjectId(...)". + + Prior to version 2.2, returns the value of the object as a + hexadecmial string. - valueOf() +- ``valueOf() `` - returns the value of the ObjectId() object as a hexadecimal string. - The returned string is the ``str`` attribute. + Returns the value of the ObjectId() object as a hexadecimal string. + The returned string is the ``str`` attribute. + + Prior to version 2.2, returns the string literal "ObjectId(...)" - Prior to version 2.2, returns the string literal "ObjectId(...)" - Consider the following usage of the ObjectID() class in the :program:`mongo` shell: @@ -50,15 +52,15 @@ shell: .. code-block:: javascript - > x=ObjectId() - + > x = ObjectId() + ObjectId("507f1f77bcf86cd799439011") - Generate a new ObjectId() using the constructor with a unique hexadecimal string: .. code-block:: javascript - > y=ObjectId("507f191e810c19729de860ea") + > y = ObjectId("507f191e810c19729de860ea") ObjectId("507f191e810c19729de860ea") From 77bdcc09d704f792267d558c9a6350a9a32be175 Mon Sep 17 00:00:00 2001 From: kay Date: Wed, 17 Oct 2012 18:30:58 -0400 Subject: [PATCH 3/5] DOCS-563 and DOCS-586 minor cleanup of ObjectId --- source/core/ObjectId.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/core/ObjectId.txt b/source/core/ObjectId.txt index d3332fc9a27..0004cdc92d1 100644 --- a/source/core/ObjectId.txt +++ b/source/core/ObjectId.txt @@ -30,7 +30,7 @@ the following helper attribute and methods: The hexadecimal string value of the ObjectID() object. -- ``toString() `` +- ``toString()`` Returns the string representation of the ObjectId() object. The returned string literal has the format "ObjectId(...)". @@ -38,7 +38,7 @@ the following helper attribute and methods: Prior to version 2.2, returns the value of the object as a hexadecmial string. -- ``valueOf() `` +- ``valueOf()`` Returns the value of the ObjectId() object as a hexadecimal string. The returned string is the ``str`` attribute. From 131715dd96262307d0461b3e7c8ac694bd4a1a3e Mon Sep 17 00:00:00 2001 From: kay Date: Thu, 18 Oct 2012 11:51:49 -0400 Subject: [PATCH 4/5] DOCS-563 586 add ObjectId() getTimestamp method and blurb --- source/core/ObjectId.txt | 34 +++++++++++++++---- .../method/ObjectId.getTimestamp.txt | 20 +++++++++++ 2 files changed, 47 insertions(+), 7 deletions(-) create mode 100644 source/reference/method/ObjectId.getTimestamp.txt diff --git a/source/core/ObjectId.txt b/source/core/ObjectId.txt index 0004cdc92d1..731f0511cb0 100644 --- a/source/core/ObjectId.txt +++ b/source/core/ObjectId.txt @@ -13,11 +13,19 @@ In MongoDB, documents stored in a collection require a unique :term:`_id` field that acts as a :term:`primary key`. Because ``ObjectIds`` are small, most likely unique, and fast to generate, MongoDB uses ``ObjectIds`` as the default value for the ``_id`` field -if the ``_id`` field is not specified. +if the ``_id`` field is not specified; i.e., the :program:`mongod` adds +the ``_id`` field and generates a unique ``ObjectId`` to assign as its +value. -If a document is missing the ``_id`` field during a create -operation, the :program:`mongod` adds the ``_id`` field and generates a -unique ``ObjectId`` to assign as its value. +Since the ``ObjectId`` contains the timestamp of its generation, using +the ``ObjectId`` as the default value for the ``_id`` field provides +these additional benefits: + +- Storing of the create timestamp is inherent and easily accessible + with the ``getTimestamp()`` method. + +- Sorting by the ``_id`` field is analogous to sorting by the create + timestamp. ObjectId() ---------- @@ -30,6 +38,10 @@ the following helper attribute and methods: The hexadecimal string value of the ObjectID() object. +- ``getTimestamp()`` + + Returns the timestamp portion of the ObjectId() object as a Date. + - ``toString()`` Returns the string representation of the ObjectId() object. The @@ -64,11 +76,19 @@ shell: ObjectId("507f191e810c19729de860ea") +- Get the timestamp of an ObjectId() object: + + .. code-block:: javascript + + > ObjectId("507f191e810c19729de860ea").getTimestamp() + + ISODate("2012-10-17T20:46:22Z") + - Access the ``str`` attribute of an ObjectId() object: .. code-block:: javascript - > y.str + > ObjectId("507f191e810c19729de860ea").str 507f191e810c19729de860ea @@ -76,7 +96,7 @@ shell: .. code-block:: javascript - > y.toString() + > ObjectId("507f191e810c19729de860ea").toString() ObjectId("507f191e810c19729de860ea") @@ -84,6 +104,6 @@ shell: .. code-block:: javascript - > y.valueOf() + > ObjectId("507f191e810c19729de860ea").valueOf() 507f191e810c19729de860ea diff --git a/source/reference/method/ObjectId.getTimestamp.txt b/source/reference/method/ObjectId.getTimestamp.txt new file mode 100644 index 00000000000..9d91eb4aa82 --- /dev/null +++ b/source/reference/method/ObjectId.getTimestamp.txt @@ -0,0 +1,20 @@ +======================= +ObjectId.getTimestamp() +======================= + +.. default-domain:: mongodb + +.. method:: ObjectId.getTimestamp() + + Returns the timestamp portion of the ObjectId() object as a Date. + + In the following example, the :method:`getTimestamp + ` method for + ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns + ``ISODate("2012-10-15T21:26:17Z")``: + + .. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").getTimestamp() + + ISODate("2012-10-15T21:26:17Z") From 4da33114d0aaab99115cab55510005ee841d9fee Mon Sep 17 00:00:00 2001 From: kay Date: Thu, 18 Oct 2012 15:14:05 -0400 Subject: [PATCH 5/5] DOCS-584 ObjectId valueOf and toString release notes --- source/core/ObjectId.txt | 4 +- .../method/ObjectId.getTimestamp.txt | 3 +- source/reference/method/ObjectId.toString.txt | 8 ++- source/reference/method/ObjectId.valueOf.txt | 26 ++++--- source/release-notes/2.2.txt | 69 +++++++++++++++++++ 5 files changed, 95 insertions(+), 15 deletions(-) diff --git a/source/core/ObjectId.txt b/source/core/ObjectId.txt index 731f0511cb0..104bb94111c 100644 --- a/source/core/ObjectId.txt +++ b/source/core/ObjectId.txt @@ -27,6 +27,8 @@ these additional benefits: - Sorting by the ``_id`` field is analogous to sorting by the create timestamp. +.. _core-object-id-class: + ObjectId() ---------- @@ -55,7 +57,7 @@ the following helper attribute and methods: Returns the value of the ObjectId() object as a hexadecimal string. The returned string is the ``str`` attribute. - Prior to version 2.2, returns the string literal "ObjectId(...)" + Prior to version 2.2, returns the object ObjectId(...) Consider the following usage of the ObjectID() class in the :program:`mongo` shell: diff --git a/source/reference/method/ObjectId.getTimestamp.txt b/source/reference/method/ObjectId.getTimestamp.txt index 9d91eb4aa82..f98fec86b9b 100644 --- a/source/reference/method/ObjectId.getTimestamp.txt +++ b/source/reference/method/ObjectId.getTimestamp.txt @@ -6,7 +6,8 @@ ObjectId.getTimestamp() .. method:: ObjectId.getTimestamp() - Returns the timestamp portion of the ObjectId() object as a Date. + Returns the timestamp portion of the :ref:`ObjectId() + ` object as a Date. In the following example, the :method:`getTimestamp ` method for diff --git a/source/reference/method/ObjectId.toString.txt b/source/reference/method/ObjectId.toString.txt index 76e3abb309e..24d42628338 100644 --- a/source/reference/method/ObjectId.toString.txt +++ b/source/reference/method/ObjectId.toString.txt @@ -8,8 +8,8 @@ ObjectId.toString() .. versionchanged:: 2.2 - Returns the string representation of the ObjectId() object and has the - format ``ObjectId(...)``. + Returns the string representation of the :ref:`ObjectId() + ` object and has the format ``ObjectId(...)``. In the following example, the :method:`toString ` method for @@ -22,6 +22,10 @@ ObjectId.toString() ObjectId("507c7f79bcf86cd7994f6c0e") + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + string + .. note:: Prior to version 2.2, the :method:`toString diff --git a/source/reference/method/ObjectId.valueOf.txt b/source/reference/method/ObjectId.valueOf.txt index f5ad61c37c7..85993eded97 100644 --- a/source/reference/method/ObjectId.valueOf.txt +++ b/source/reference/method/ObjectId.valueOf.txt @@ -6,24 +6,28 @@ ObjectId.valueOf() .. method:: ObjectId.valueOf() - .. versionchanged:: 2.2 - - Returns the value of the ObjectId() object as a lowercase - hexadecimal string. More precisely, the method returns the ``str`` - attribute of the ObjectId() object. - + .. versionchanged:: 2.2 + + Returns the value of the :ref:`ObjectId() ` + object as a lowercase hexadecimal string. More precisely, the method + returns the ``str`` attribute of the ObjectId() object. + In the following example, the :method:`valueOf ` method for ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns the hexadecimal string ``507c7f79bcf86cd7994f6c0e``: - + .. code-block:: javascript - + > ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() - + 507c7f79bcf86cd7994f6c0e - + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + string + .. note:: Prior to version 2.2, :method:`valueOf ` - method returns the string literal, e.g. + method returns the object, e.g. ``ObjectId("507c7f79bcf86cd7994f6c0e")``. diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index edc1dc3eb84..35bd5a3b704 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -301,6 +301,75 @@ database. See: :issue:`SERVER-6961` for more information. +.. _2.2-ObjectId-toString-valueOf-methods: + +``ObjectId().toString()`` Returns String Literal ``ObjectId("...")`` +```````````````````````````````````````````````````````````````````` + +In version 2.2, the :method:`ObjectId.toString()` method returns the +string representation of the :ref:`ObjectId() ` +object and has the format ``ObjectId("...")``. + +.. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + ObjectId("507c7f79bcf86cd7994f6c0e") + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + string + +Previously, in version 2.0, the method would return the hexadecimal +string. + +.. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + 507c7f79bcf86cd7994f6c0e + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").toString() + + string + +If compatibility between versions 2.0 and 2.2 is required, use +ObjectId().str, which holds the hexadecimal string value in both +versions. + +``ObjectId().valueOf()`` Returns hexadecimal string +``````````````````````````````````````````````````` + +In version 2.2, the :method:`ObjectId.valueOf()` method returns the +value of the :ref:`ObjectId() ` object as a +lowercase hexadecimal string. + +.. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + 507c7f79bcf86cd7994f6c0e + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + string + +Previously, in version 2.0, the method would return the object. + +.. code-block:: javascript + + > ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + ObjectId("507c7f79bcf86cd7994f6c0e") + + > typeof ObjectId("507c7f79bcf86cd7994f6c0e").valueOf() + + object + +If compatibility between versions 2.0 and 2.2 is required, use +ObjectId().str, which holds the hexadecimal string value in both +versions. + Behavioral Changes ~~~~~~~~~~~~~~~~~~