DOCS-563 DOCS-586 ObjectId class methods and field doc

source/applications.txt

@@ -32,6 +32,7 @@ The following documents outline basic application development topics:
 
    applications/drivers
    applications/database-references
+   core/ObjectId
 
 .. seealso:: 
 

source/core/ObjectId.txt

@@ -0,0 +1,111 @@
+========
+ObjectId
+========
+
+:term:`ObjectId <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 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; i.e., 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.
+
+.. _core-object-id-class:
+
+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:
+
+- ``str``
+
+   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
+   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 object 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")
+
+- 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
+
+     > ObjectId("507f191e810c19729de860ea").str
+
+     507f191e810c19729de860ea
+
+- Get the string representation of an ObjectId() object:
+
+  .. code-block:: javascript
+
+     > ObjectId("507f191e810c19729de860ea").toString()
+
+     ObjectId("507f191e810c19729de860ea")
+
+- Get the value of an ObjectId() object as a hexadecimal string:
+
+  .. code-block:: javascript
+
+     > ObjectId("507f191e810c19729de860ea").valueOf()
+
+     507f191e810c19729de860ea

source/reference/method/ObjectId.getTimestamp.txt

@@ -0,0 +1,21 @@
+=======================
+ObjectId.getTimestamp()
+=======================
+
+.. default-domain:: mongodb
+
+.. method:: ObjectId.getTimestamp()
+
+   Returns the timestamp portion of the :ref:`ObjectId()
+   <core-object-id-class>` object as a Date.
+
+   In the following example, the :method:`getTimestamp
+   <ObjectId.getTimestamp()>` method for
+   ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns
+   ``ISODate("2012-10-15T21:26:17Z")``:
+
+   .. code-block:: javascript
+
+      > ObjectId("507c7f79bcf86cd7994f6c0e").getTimestamp()
+
+      ISODate("2012-10-15T21:26:17Z")

source/reference/method/ObjectId.toString.txt

@@ -0,0 +1,35 @@
+===================
+ObjectId.toString()
+===================
+
+.. default-domain:: mongodb
+
+.. method:: ObjectId.toString()
+
+   .. versionchanged:: 2.2
+
+   Returns the string representation of the :ref:`ObjectId()
+   <core-object-id-class>` object and has the format ``ObjectId(...)``.
+
+   In the following example, the :method:`toString
+   <ObjectId.toString()>` method for
+   ``ObjectId("507c7f79bcf86cd7994f6c0e")`` returns the string literal
+   ``ObjectId("507c7f79bcf86cd7994f6c0e")``:
+
+   .. code-block:: javascript
+
+      > ObjectId("507c7f79bcf86cd7994f6c0e").toString()
+
+      ObjectId("507c7f79bcf86cd7994f6c0e")
+
+      > typeof ObjectId("507c7f79bcf86cd7994f6c0e").toString()
+
+      string
+
+   .. note::
+
+      Prior to version 2.2, the :method:`toString
+      <ObjectId.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.

source/reference/method/ObjectId.valueOf.txt

@@ -0,0 +1,33 @@
+==================
+ObjectId.valueOf()
+==================
+
+.. default-domain:: mongodb
+
+.. method:: ObjectId.valueOf()
+
+   .. versionchanged:: 2.2
+
+   Returns the value of the :ref:`ObjectId() <core-object-id-class>`
+   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 <ObjectId.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 <ObjectId.valueOf()>`
+      method returns the object, e.g.
+      ``ObjectId("507c7f79bcf86cd7994f6c0e")``.

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() <core-object-id-class>`
+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() <core-object-id-class>` 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
 ~~~~~~~~~~~~~~~~~~